% LaTeX input for the "OzTeX User Guide".
% Non-LaTeX cross references are flagged by "XREF".
% Unfinished or uncertain portions are flagged by "!!!" or "???".

\documentclass[11pt]{article}

\oddsidemargin=0in
\evensidemargin=0in
\textwidth=6.3in

\topmargin=-0.5in
\headheight=0.2in
\headsep=0.5in
\textheight=9.4in                  % better for US Letter paper

\input OzTeX                       % for \OzTeX and \OzTools
\let\pOzTeX=\OzTeX
\let\pOzTools=\OzTools
\def\OzTeX{\protect\pOzTeX}        % protect "OzTeX" in page headings
\def\OzTools{\protect\pOzTools}    % protect "OzTools" in page headings

\font\logo=logo10 scaled\magstephalf

\def\readme{{\tt Read-Me}}
\def\ozprefs{{\tt OzTeX~Prefs}}
\def\texbook{{\sl The \TeX book\/}}
\def\initex{{\tt INITEX\null}}
\def\configs{{\tt Configs}}
\def\globalps{{\tt global.ps}}
\def\oztext{{\tt Oz.text}}
\def\pool{{\tt TeX.pool}}
\def\textpro{{\tt TEXTtoPS.pro}}
\def\lowpro{{\tt DVItoPS.pro}}
\def\stdpro{{\tt OzTeXdict.pro}}
\def\pkfiles{{\tt PK-files}}
\def\psfiles{{\tt PS-files}}
\def\encfiles{{\tt Encodings}}
\def\stdenc{{\tt Mac.enc}}
\def\vffiles{{\tt VF-files}}
\def\texfonts{{\tt TeX-fonts}}
\def\texinputs{{\tt TeX-inputs}}
\def\texformats{{\tt TeX-formats}}
\def\helpfiles{{\tt Help-files}}
\def\texdocs{{\tt TeX-docs}}
\def\latexdocs{{\tt LaTeX-docs}}
\def\ttedit{{\tt BBEdit~Lite}}
\def\bbedit{BBEdit~Lite}
\def\dvf{{\tt Dvips}}
\def\dvips{{\tt dvips}}
\def\mff{{\tt Metafont}}
\def\mf{{\logo METAFONT\null}}
\def\configps{{\tt config.ps}}
\def\missfont{{\tt missfont.log}}

\raggedbottom

\begin{document}

\null
\vfil

\centerline{\hbox to 30bp{\special{pntg=ozicon}\hfil}}
\bigskip

\begin{center}
\Huge\bf
\OzTeX\ User Guide\\ [3mm]
\normalsize\bf
Version 1.9, May 1995\\ [3mm]
\rm
Andrew Trevorrow\\
akt@kagi.com
\end{center}

\bigskip
\bigskip

\noindent
\OzTeX\ is a shareware version of \TeX\ for the Macintosh
(see \OzTeX's Help menu for details about the shareware fee).
This document assumes you know how to use a Macintosh.
It also assumes you are familiar with \TeX,
the typesetting system developed by Donald Knuth at Stanford University.
An understanding of PostScript is not essential but would be useful
if you have access to a PostScript printer.

\OzTeX\ aims to provide a standard \TeX\ environment for the Macintosh
that can easily be extended or customized to suit your particular needs.
If you have had experience with \TeX\ on some other computer then the way
\OzTeX\ works shouldn't be too surprising.

Comments, bug reports and suggestions are all welcome, but
please note that I only reply to e-mail queries from registered
\OzTeX\ users.

\vfil

\thispagestyle{empty}

\pagenumbering{roman}

\newpage

\pagestyle{headings}

\tableofcontents

\newpage

\pagenumbering{arabic}


\section{Introduction}

Assuming you correctly carried out the installation instructions in the
\readme\ file supplied with \OzTeX, you should have a folder that looks
something like this:

\vbox to 2.5in{\label{folders}\vfil
\noindent\hskip 1.1in\special{pntg=folders scale=0.72}}

\bigskip

\noindent
Here is a brief description of the various folders:
\begin{itemize}

\item
The \texinputs\ folder contains a large number of \TeX\ input files
stored in various sub-folders.  \TeX\ looks in these sub-folders if it can't
find a given file in your current folder.

\item
The \texformats\ folder contains the format files read by \TeX\ and
the \pool\ file read by \initex.
Section~\ref{fmt-sec} describes how to create format files.

\item
The \texfonts\ folder contains many \TeX\ Font Metric files
stored in various sub-folders.
These TFM files are required by \TeX\ to carry out typesetting;
see section~\ref{tfm-sec}.

\item
The \vffiles\ folder contains Virtual Font files;
see section~\ref{vf-sec}.

\item
The \psfiles\ folder contains various PostScript files.
It also contains encoding files in the \encfiles\ sub-folder;
see section~\ref{enc-sec}.

\item
The \pkfiles\ folder contains PK font files stored in various sub-folders.
The name of each sub-folder indicates the ``size'' of the PK files kept
within it; see section~\ref{pk-sec} for how this size is calculated
and for more information about PK files.
\OzTeX\ is distributed with a fairly small set of PK files (sufficient
to print out the documentation on the most common printers).
New PK files at any desired size can be built by \mf;
see section~\ref{mf-sec}.

\item
The \configs\ folder contains a number of configuration files.
Section~\ref{config-sec} discusses how these files can be used to
customize \OzTeX.

\item
The \helpfiles\ folder contains a number of text files.
The information in these files can be displayed by selecting their names
from \OzTeX's Help menu.

\item
The \texdocs\ folder contains examples of \TeX\ input files,
including \verb|nasty.tex| which is used in the guided tour of \OzTeX.
It also contains \verb|gentle.tex|, the source file for Michael Doob's
{\sl A Gentle Introduction to \TeX}\null.
\TeX\ beginners should find this a useful companion to \texbook\ by Donald Knuth.

\item
The \latexdocs\ folder contains the source files for this User Guide.

\item
The \ttedit\ folder contains the \bbedit\ application and its documentation.
\bbedit\ is a text editor by Rich Siegel which can be used to create and modify
\TeX\ input files.  If you prefer to use a different text editor then throw
away the \ttedit\ folder.

\item
The \dvf\ folder contains Tom Kiffe's implementation of \dvips;
see section~\ref{dv-sec}.

\item
The \mff\ folder contains Tom Kiffe's implementation of \mf;
see section~\ref{mf-sec}.

\end{itemize}
Please note that Tom's programs are distributed with \OzTeX\ under
a separate shareware fee; see the \readme\ file for details.
System~7 or later is needed to run these programs.


\section{Configuration files}
\label{config-sec}

\subsection{The default configuration file}

\OzTeX\ reads a configuration file called {\tt Default} when starting up.
This file is kept in the \configs\ folder along with other configuration files.
A configuration file is a simple text file which you can edit and
change various parameters that control \OzTeX's behaviour.

Before modifying the {\tt Default} config file it would be a good idea to save
a copy first.  Another good idea is to flag your changes with some sort of
unique comment so that they can be reproduced easily if and when a new
version of \OzTeX\ is released.


\subsection{The required syntax}
\label{config-syntax}

Follow these rules when editing a configuration file:
\begin{itemize}

\item
Lines starting with ``\verb|%|'' are ignored and can be used to include comments.
This is also true for lines starting with ``\verb|@|'', but in this case the rest
of the line appears in the \OzTeX\ window.
All other lines are said to be ``significant''.

\item
Each significant line must contain at least one ``\verb|=|'' character.
Any characters before the first ``\verb|=|'' are ignored, as are spaces or tabs
immediately after it.  The rest of the line contains the information used
by \OzTeX, usually in the form of one or more strings.
If only one string is required then any further information is ignored.
Use double quotes around a string that includes one or more spaces.

\item
Do \emph{not} change the order of significant lines
(except between the first and last ``\verb|==|'').
\OzTeX\ expects to find all the parameters in a fixed sequence.

\item
To avoid long significant lines you can use ``\verb-|-'' to split lines anywhere
you like.  Upon reading a ``\verb-|-'', \OzTeX\ will ignore the rest of the current
line and continue reading from the next line.  The best place to use ``\verb-|-''
is where a space is allowed; that way you can safely indent the next line
to make the file more readable.

\item
To help keep non-default configuration files short and simple, use these
special characters:
\begin{enumerate}

\item
If ``\verb|?|'' is the first character of a parameter's value
then the parameter is not changed and the rest of the line is ignored.

\item
``\verb|!|'' is similar to ``\verb|?|'' but in addition all remaining parameters
are left unchanged (in fact the rest of the file is ignored).

\end{enumerate}
Note that these characters are not recognized as special in the
{\tt Default} file because every parameter must be given a default value,
even if empty.

\end{itemize}


\subsection{The parameters}

This section discusses all the parameters in a configuration file,
in the order required by \OzTeX\null.
It would be a good idea to look at the {\tt Default} config file while
reading the following information.

%??? \subsubsection{Menu parameters}

The list of config files appear as items at the end of the Config menu
and must correspond to text files stored in the \configs\ folder.
This list is ignored in non-default configuration files.
The default config file will automatically load any config files
whose names start with ``\verb|+|''.

The list of format files appear as items at the end of the \TeX\ menu
and must correspond to the names of \verb|.fmt| files in the \texformats\ folder.
The format file names must not contain any spaces.
Place your preferred format first.

The list of help files appear as items in the Help menu and must
correspond to text files in the \helpfiles\ folder.
The Help menu will not appear if the list is empty.

NOTE: Any string starting with ``\verb|-|'' in the above three lists will result
in a disabled line in the corresponding menu.

%??? \subsubsection{Printing and previewing parameters}

The printer resolution (in dots per inch) is used when printing a DVI file
and the viewing resolution is used when viewing a DVI file.  In both cases
the maximum value is 3000 and the minimum value is the resolution of your
screen (typically 72).
Both resolution values are followed by a string specifying the mode that
will be used by \mf\ when making missing PK fonts; see section~\ref{mfmode}.

The units parameter tells \OzTeX\ how to display dimensions when
printing or viewing a DVI file.
The normal \TeX\ units are available
({\tt in}, {\tt cm}, {\tt mm}, {\tt pc}, {\tt pt}, {\tt bp})
as well as {\tt px} (see section~\ref{paper-coords}).

The paper width and height dimensions are used to detect page-off-paper
errors when viewing a DVI file and during low-level PostScript printing.
(In standard PostScript printing and non-PostScript printing,
\OzTeX\ uses the paper size and orientation selected in the ``Page Setup'' dialog.)
If the width is greater than the height then \OzTeX\ will print or view
in landscape mode.
The {\tt Default} values specify A4 paper in portrait mode.
If you use US~Letter paper then see the \verb|US Letter| config file for
suitable default values.

The horizontal and vertical offsets affect the positioning of all pages when
printing a DVI file.  They should only be changed if your printer has problems
positioning the \TeX\ origin (see page~2 in {\tt nasty.dvi}).
These offsets are \emph{not} used when viewing a DVI file.

The ``show statistics'' and other flag parameters specify the initial settings
of some check boxes used in the dialogs for printing a DVI file.

\subsubsection{Important folders and files}

\OzTeX\ needs to know the names and locations of various folders and files.
These are specified by path names.  A path name can be a simple file name,
or it can be a sequence of names separated by colons that represent a valid
location in your folder hierarchy.  If the path name ends with a colon then it
specifies a folder, otherwise a file.
\OzTeX\ will generate a warning message if a given path name does not specify a
known folder or file.  Note that under System~7, \OzTeX\ supports aliased files
but not aliased folders.

Partial path names begin with a colon.  The first folder in such a path is
assumed to be in the same location as the \OzTeX\ application.  This is the best
way to specify folders and files because then you can move the entire
\OzTeX\ folder anywhere you like without having to change any path names.

Full path names begin with the name of a disk;
e.g., \verb|HD:OzTeX:Help-files:|.
Path names must be enclosed in double quotes if they contain any spaces;
e.g., \verb|":My help:"|.

\OzTeX\ can be told to search in more than one folder for
\TeX\ input files, TFM files, PK files, PS files and VF files.
The corresponding parameters also allow ``\verb|*|'' at the end of a path name to
tell \OzTeX\ to include all sub-folders of the given folder in the search path.
\OzTeX\ does \emph{not} automatically include sub-folders within sub-folders.

\subsubsection{Previewing colours}

A number of elements can be coloured when previewing a DVI file;
they are the paper edges, \verb|\special| markers and missing fonts.
The allowed colours are black, red, green, blue, cyan, magenta, yellow and
white (white can be used to make something invisible).  On black and white
monitors all non-white colours appear black.

\subsubsection{\TeX\ parameters}

The \TeX\ parameters determine how much memory is allocated for various arrays
used by \TeX\ and \initex.  Note that \verb|mem_max| is temporarily set to
\verb|mem_top| whenever you run \initex.

Comments in the {\tt Default} file indicate the possible range of values
for each parameter.
The {\tt Default} values are suitable for small to medium-size \TeX\ documents.
If you decide to increase one or more of these parameters then
you may need to increase \OzTeX's application memory size
(via ``Get Info'' in the Finder's File menu).  Note that a change to
\verb|mem_top|, \verb|hash_size|, \verb|hash_prime| or \verb|hyf_size|
will require rebuilding all format files; see section~\ref{fmt-sec}.

\subsubsection{PostScript fonts}

The lines between the first and last ``\verb|==|'' tell \OzTeX\ which TFM files
are for PostScript fonts (or more accurately, non-PK fonts).
The ordering of lines doesn't matter; they are used by \OzTeX\ to build a list
of PostScript fonts.
In a non-default config file the first ``\verb|==|'' can be replaced by ``\verb|=+|'';
this tells \OzTeX\ to \emph{update} the current list rather than delete it
and build a new one.

Each line specifies a TFM name, a printer font name, an optional download file,
a screen font name, an encoding entry and an optional style.
Note that most of the lines in the {\tt Default} file contain ``raw'' TFMs for
corresponding virtual fonts; see section~\ref{vf-sec}.

If a DVI file uses PostScript fonts, the TFM names get converted into
printer font names when printing the file on a PostScript printer.
\OzTeX\ allows non-resident PostScript fonts to be downloaded on demand.
The Utopia lines at the end of the {\tt Default} file have an extra string
(starting with ``\verb|<|'') after the printer font name.
This specifies the file to be downloaded if the corresponding font is used;
see section~\ref{ps-fonts} for more information.

The screen font names are used when viewing a DVI file with PostScript fonts,
and when printing the file on a non-PostScript printer.
If you are unsure about which screen font would best match a particular
PostScript font, you must still specify something (such as ``\verb|?|'').
If \OzTeX\ can't find a specified screen font it will warn you and use
the system font instead.
To obtain the best results when viewing or printing a DVI file with
PostScript fonts you must get the matching screen fonts.

Each screen font can appear in a certain style defined by a set of flags:
``{\tt b}'' for bold,
``{\tt i}'' for italic,
``{\tt u}'' for underline,
``{\tt o}'' for outline,
``{\tt s}'' for shadow,
``{\tt c}'' for condense and
``{\tt e}'' for extend.
If the style is not specified then \OzTeX\ uses the font's plain style.

An encoding entry is the name of a user-defined encoding file
(or ``{\tt nil}'' if the TFM file and screen font use the same encoding).
Section~\ref{enc-sec} discusses encoding files.


\subsection{Other configuration files}

\OzTeX's Config menu lets you switch rapidly from one configuration file to
another.  This is especially useful if you have access to more than one printer
because each printer will probably require a separate configuration file.
There are many other uses for configuration files;
see section~\ref{other-configs} for a brief description of the various
config files supplied with \OzTeX\null.
It is a simple matter to create your own files and add their names to the list
in the {\tt Default} file.

\newpage


\section{A guided tour of \OzTeX}

The aim of this section is to get you acquainted with \OzTeX's major features.


\subsection{Starting \OzTeX}

Assuming you've installed everything, double-click on the
\OzTeX\ application file to get the program started.
After a brief pause you should see a window with the title ``\OzTeX''
and a couple of messages showing the current version of \OzTeX\ and
the path name of the {\tt Default} configuration file just loaded.
The {\tt Default} file's list of PostScript fonts contains references
to an encoding file, so it will also be loaded.   % XREF

If you made a mistake during installation, or when editing
the {\tt Default} file, then you might also get one or more error messages.
The messages should give you some idea of how to fix the problem.

The \OzTeX\ window is always present; note that it has no close box
in the top left corner.
This window provides a terminal-like interface for \OzTeX\null.
It cannot be edited, but you can copy its contents to the Clipboard
or save it to a text file.

You can also start up \OzTeX\ by double-clicking on any \OzTeX-created file
ending in \verb|.xxx|; e.g., \verb|foo.log| or \verb|foo.dvi|.
The advantage of this start up method is that \verb|foo.tex| will appear in
the \TeX\ menu and \verb|foo.dvi| will appear in the Print and View menus.
Also, if \verb|foo.log| exists and contains a known format then \OzTeX\ will
automatically make this the current format so you can immediately typeset
\verb|foo.tex| by hitting Command-T\null.
If \verb|foo.tex| can't be found then \OzTeX\ will look for \verb|foo.ltx|
(this is a popular file naming scheme used to distinguish \LaTeX\ input files).
Under System~7, you can drag-and-drop \verb|foo.tex| or \verb|foo.ltx|
onto the \OzTeX\ icon and \OzTeX\ will immediately typeset the file.

The production of a \TeX\ document typically involves a number of iterations
through the following cycle: edit, typeset, preview and print.
(People concerned about our dwindling forests will hopefully preview
many more times than they print.)
Let's go through this cycle step by step.


\subsection{Choosing an editor}

\OzTeX\ does not have an integrated text editor, but if you are using
System~7 or later you won't find this too much of a problem.
After installing \OzTeX\ and starting it up for the very first time,
select ``Choose Editor'' from the Edit menu and use the
standard file dialog to locate and select the application you'll be using
to edit your \TeX/\LaTeX\ input files.
If the chosen application supports Apple events then \OzTeX\ remembers
its name and location for use in all future \OzTeX\ sessions (or until
you choose another editor).

Having chosen an editor, \OzTeX\ will use it as the target of an
``open file'' event sent when you select ``Edit foo.tex'' from the Edit menu.
This item always shows the name of the most recently typeset file.
See section~\ref{edit-menu} for more details about the items in the Edit menu.


\subsection{Editing a \TeX\ input file}

A \TeX\ input file is a standard Macintosh text file.
We won't create an input file from scratch, instead we'll use one
of the sample files provided in the \texdocs\ folder.
There is nothing special about this folder, or \latexdocs.
I simply like to keep my \TeX\ and \LaTeX\ input files in separate folders.
You can keep your input files anywhere you like.

The file we'll use is called \verb|nasty.tex|.
As the name suggests, it is not a typical \TeX\ input file,
but it does illustrate most of the things you'll encounter when using
\OzTeX\ in the future.

Switch to your text editor and open \verb|nasty.tex| from the \texdocs\ folder.
The only change we'll make to \verb|nasty.tex| is to add a deliberate error:
insert the illegal command \verb|\xxx| at the start of the file.
Save this change before switching back to \OzTeX.


\subsection{Running \TeX}

Let's now typeset \verb|nasty.tex|.
Before starting \TeX\ we need to make sure that the correct format will be used.
(This check is not normally needed if the log file exists and
``Use Format in Log'' is ticked.  However, when typesetting a file
for the very first time it is best to manually set the correct format.)
All the available formats appear at the end of the \TeX\ menu.
Check this menu and make sure the Plain format is ticked;
this is the format required by \verb|nasty.tex|.

Choose ``\TeX\,\ldots'' from the \TeX\ menu and open \verb|nasty.tex|.
The \OzTeX\ window will be cleared, \TeX\ will start up,
load the Plain format, and begin reading the given input file.

When it sees the unknown command, \TeX\ will display a suitable error message,
beep, and wait for you to type something.
Note that a solid block cursor sits next to \TeX's ``\verb|?|'' prompt.
This block cursor always appears when \TeX\ is waiting for you to type something.
The \OzTeX\ window should contain the following:

\bigskip

\indent\verb|This is TeX, Version 3.14159 (no format preloaded)|\\
\indent\verb|**&Plain nasty.tex|\\
\indent\verb|(nasty.tex|\\
\indent\verb|! Undefined control sequence.|\\
\indent\verb|l.5 \xxx|\\
\indent\\
\indent\verb|? |{\tt\vrule width .4em height .7em depth .15em}

\bigskip

\noindent
Chapter 6 in \texbook\ explains what you can do in such a situation.
(Section~\ref{edit-menu} describes how you can type ``\verb|e|'' to tell
\OzTeX\ to switch to your editor and open the file containing the error,
possibly with the error line selected.)
In this case we can simply ignore the error and continue
by hitting the Return key.
Although \verb|nasty.tex| is not very nice, you shouldn't see any more
\TeX\ errors.  A 19-page DVI file called \verb|nasty.dvi| should be created.

Have a look at the second item in both the File and View menus.
Whenever a new DVI file is created, its name will automatically appear in
these items so you can quickly print or view the DVI file
without going through the standard file dialog.
The second item in the \TeX\ menu has also been updated with the name
of the most recent input file (\verb|nasty.tex| in this case), so you can
easily typeset the same file again by pressing Command-T\null.
The file name also appears in the bottom item of the Edit menu   % XREF
so you can quickly switch back to your editor by pressing Command-E\null.

\OzTeX\ supports background typesetting.  At any time while \TeX\ is running you
can switch to another application and \TeX\ will continue to run in the background.
Whenever \OzTeX\ finishes a lengthy task in the background (like typesetting
or printing), or if some sort of user interaction is required (say a \TeX\ error
occurs), then under System~6 or later you will be notified by a flashing
\OzTeX\ icon in the menu bar.  A diamond mark will also appear next to
\OzTeX\ in the list of current applications.


\subsection{Checking for virtual fonts}

Before proceeding to view or print a DVI file created for the first time,
it is a good idea to check and see if any virtual fonts are used
(section~\ref{vf-sec} has more information about virtual fonts).
Select ``Fix VFs in DVI'' from the \TeX\ menu and open \verb|nasty.dvi|.
\OzTeX\ lists all the fonts used in the DVI file and prefixes each font
with its type:

\bigskip

PK indicates a packed pixel font (see section~\ref{pk-sec});\par
PS indicates a PostScript font (see section~\ref{ps-fonts});\par
VF indicates a virtual font.\par

\bigskip

\noindent
As it happens, \verb|nasty.dvi| does use a couple of virtual fonts,
so \OzTeX\ processes every page, fixes all virtual font references
and creates a new version of \verb|nasty.dvi|.

If your documents use virtual fonts, it is advisable to tick
``Fix VFs after \TeX'' in the \TeX\ menu;
then you don't have to remember to run ``Fix VFs in DVI'' before
viewing or printing a DVI file.


\subsection{Viewing a DVI file}

The next step is to preview the DVI file and check for
problems that \TeX\ may have missed, like missing fonts, bad page breaks,
spelling mistakes, etc.
Let's have a look at \verb|nasty.dvi| by choosing the second item in
the View menu.
\OzTeX\ creates a new window, called the ``view'' window, and sets its
title to the selected DVI file.  A dialog box has also appeared:

\vbox to 1.6in{\label{viewdlg}\vfil
\noindent\hskip 1.0in\special{pntg=viewdlg scale=0.72}}

\bigskip

\noindent
The scroll bar allows you to select any page in the DVI file.
There are also two edit boxes in which you can type a DVI page number
or \TeX\ page number.
(The dialog box also allows you to change some other options, but
we'll ignore them at this stage; see the description of ``View DVI\,\ldots''
on page~\pageref{view-menu} for details.)
Play around with the scroll bar if you like but make sure
the 2nd DVI page is selected before proceeding.
To view this page simply click in the View button or hit the Return key.

The 2nd page in \verb|nasty.dvi| contains a single rule with some text below it. % XREF
Dotted lines representing the paper edges should also be visible.
Now is a good time to adjust the size and location of the \OzTeX\ and view
windows to suit your screen.  When you quit, \OzTeX\ will remember the current
window settings and use them the next time it starts up.

\subsubsection{Setting the default view}
\label{def-view}

\OzTeX\ displays the top left corner of the paper at a scale approximating
the document's actual size (see below for more about scaling).   % XREF
This is the initial default view, but it might not suit the size
or dimensions of your particular monitor.  To change the default view,
you just set up the desired scale and/or location using the various
commands described below   % XREF
and then select ``Save as Default View'' from the View menu.
\OzTeX\ remembers your new default view until you decide to change it.

To restore the initial default view, simply select ``Actual Size''
from the View menu, move the scroll bar thumb boxes up and to the left
as far as possible, then select ``Save as Default View''.

\subsubsection{Paper coordinates}
\label{paper-coords}

An understanding of the coordinate system used by \OzTeX\ to view
(and print) a DVI page would be useful.
The {\tt px} units mentioned earlier are ``paper pixels'';
they are \OzTeX's internal units.
The resolution parameters in a configuration file define the
number of paper pixels per inch; one parameter is only used when printing
a DVI file and the other is only used when viewing a DVI file.

\OzTeX\ uses a coordinate scheme in which the paper pixel at (0,0) is
exactly one inch in from the top and left edges of the paper.
This position is referred to as the ``\TeX\ origin'' because it is also
the origin of the coordinate system used in DVI files.
Every character, rule or \verb|\special| has a specific location
defined by a pair of paper pixels ($h$,$v$).
Vertical coordinates increase down the paper and
horizontal coordinates increase to the right.

If the view window is frontmost then the cursor is changed to a cross
whenever it moves over the contents region.  The current position of the
cross is shown (in paper coordinates) in a box at the lower left corner
of the view window.  You can click in this box to change units.

\subsubsection{Zooming in and out}

A ``scale factor'' is used to display a DVI page at a particular size.
It defines the number of paper pixels in each Macintosh screen pixel
(both horizontally and vertically) and always has an integer value
greater than or equal to~1.
Certain View menu items change the current scale factor:
\begin{itemize}
\itemsep=0pt
\item
``Full View'' sets the scale factor to its maximum value and displays
the entire page and paper edges in the middle of the view window.
\item
``Actual Size'' sets the scale factor so that the new view will show the
page at roughly the right size
(it's only approximate because the scale factor is an integer value).
\item
``Zoom In'' halves the current scale factor.
\item
``Zoom Out'' doubles the current scale factor.
\end{itemize}
You can also change the scale factor by clicking in the view window
in a variety of ways:
\begin{itemize}
\itemsep=0pt
\item
Click-and-drag within the viewing area to zoom in to the selected rectangle.
If you want to cancel the operation then make the rectangle very thin
(not small, because that might be interpreted as a simple click).
\item
A simple click will zoom in by halving the scale factor.
\item
Command-click will zoom in by decrementing the scale factor.
\item
Option-click will zoom out by incrementing the scale factor.
\item
Shift-click will zoom out by doubling the scale factor.
\item
Option-Command-click will temporarily magnify a small area under the cursor
until the mouse button is released.  The scale factor in the magnified area is~1.
\item
A beep occurs if you can't zoom in or out any further.
\end{itemize}
When you zoom in or out by clicking, \OzTeX\ will try to make the
point you clicked the middle of the new view.
However, when you choose a menu item, \OzTeX\ tries to keep the top left
page location fixed.
In both cases it is possible that the view may unexpectedly shift so that it
remains within the scrolling limits set by \OzTeX\null.
Experiment with the various ways of zooming to see which methods you prefer.

The most precise display occurs when the scale factor is~1
because each screen pixel corresponds to exactly one paper pixel.
\OzTeX\ doesn't allow you to zoom in any further than this.

\subsubsection{Scrolling around}

The view window has scroll bars that allow you to
move over the page in the standard Macintosh manner.
Note that the arrow keys can be used instead of clicking in the scroll arrows.
\OzTeX\ won't let you get too far away from the page/paper boundaries.
If you do manage to get lost just choose ``Full View''.

\subsubsection{Checking for errors}

It is a good idea to select the ``Page Info'' item at least once while
viewing a DVI file.
This item displays its results in the \OzTeX\ window.
The display includes a list of all the fonts used in the DVI file and
clearly indicates any that are missing.
It also lists any \verb|\special| commands on the current page,
showing their locations and arguments.

\subsubsection{Selecting pages}

There are a number of interesting pages in \verb|nasty.dvi|.
Use ``Previous Page'', ``Next Page'' or ``Go to Page\,\ldots'' to
have a look at some of them.
Note that the current DVI/\TeX\ page numbers are always displayed in the
view window's title bar.  Here are some points of interest:
\begin{itemize}
\item
The current scale factor and page location will only change if the selected page
is off the paper, in which case \OzTeX\ will beep and display a full view.
Pages 13 to 15 illustrate this behaviour.
When you move from such a page to a normal page, \OzTeX\ switches back to the
default view.
\item
\OzTeX\ may take a little while to interpret and display a selected page,
depending on how complicated it is.
Hit Command-C or Command-Dot if you get bored.
\item
The view window is updated in the following manner.
Visible paper edges are drawn first, then \verb|\special| bitmaps and markers,
then rules, then characters on a font by font basis, starting with the
font that has the least number of characters on the page.
Try a full view of page 19.
\item
Page 3 has examples of \verb|\special| commands.
\OzTeX\ is able to preview included files of type PICT, PNTG or EPSF;
see section~\ref{graphics} for more information.
The location of each \verb|\special| is indicated by a small marker.
Note that the size of this marker does not change as you zoom in or out.
\item
Page 9 uses a couple of PostScript fonts; see section~\ref{ps-fonts}.
\item
All the fonts used on page 12 are deliberately missing.
\item
Page 16 has examples of bad \verb|\special| commands.
\end{itemize}
When you have finished previewing the DVI file just click in the view window's
close box.  The view window is also closed automatically when you
run \TeX, print a DVI file or load a configuration file.

\newpage


\subsubsection{Keyboard short cuts}
\label{shortcuts}

\OzTeX\ provides a number of keyboard short cuts to make it easier to
proofread a DVI file:
\begin{itemize}
\item
Type ``\verb|g|'' to go to a given page and switch to the default view.
\item
Type ``\verb|f|'' to move to the first page.
The current scale and location do not change.
\item
Type ``\verb|l|'' to move to the last page.
The current scale and location do not change.
\item
Type ``\verb|n|'' to move to the top of the next page without changing the
current scale or horizontal position.
\item
Type ``\verb|b|'' to move to the bottom of the previous page without changing
the current scale or horizontal position.
\item
Hit the space bar to scroll forwards through a document.
\item
Hit the Delete key to scroll backwards.
\item
Hit the Return key to bring either the view window or the \OzTeX\ window
to the front.
\item
Type ``\verb|w|'' to close the view window.
\item
Type ``\verb|o|'' to bypass the view dialog and open the most recently viewed
DVI page (or page 1 if you haven't viewed anything yet).  \OzTeX\ will also
restore the scale factor and location you last used.
\end{itemize}
Note that if the page selected by any of the above short cuts is off the paper
then \OzTeX\ will beep and switch to a full view.


\subsection{Printing a DVI file}

Before printing a DVI file it is a good idea to select ``Page Setup'' from the
File menu and make sure the paper size and orientation are correct.
To print \verb|nasty.dvi| choose either of the top two items in the File menu. % XREF
Choosing the second item simply avoids the standard file dialog.

\OzTeX\ tries to support all Macintosh printers, but it also tries
to take advantage of the sophisticated features available in PostScript printers.
This has often meant going against Apple's guidelines for device-independent
printing, so \OzTeX's printing code has had a long and interesting history!
All this is half-explanation and half-apology for what might seem to be an
unnecessarily complicated printing strategy.

\OzTeX\ supports four(!) methods of printing a DVI file:
\begin{enumerate}
\item Non-PostScript printing.
\item Low-level PostScript printing.
\item Standard PostScript printing.
\item Using \dvips.
\end{enumerate}
Of course, most people will only ever use one or two of these methods.
The printing method chosen by \OzTeX\ depends on whether or not the current printer
(selected in the Chooser) is a PostScript device, and the current state of two flags
in the File menu: ``Use Standard PostScript'' and ``Use DVIPS''.

If ``Use DVIPS'' is ticked then \OzTeX\ ignores both the current printer
and the ``Use Standard PostScript'' flag.  Instead, it will call \dvips\ to
translate the DVI file into a PostScript file, as described in section~\ref{dv-sec}.
If ``Use DVIPS'' is not ticked then one of the following three   % XREF
printing methods will be selected.

\subsubsection{Non-PostScript printing}

If the current printer is not a PostScript device
then the ``Use Standard PostScript'' flag is ignored.
\OzTeX\ will open the DVI file and display a printer-specific dialog.
(If the printer resolution parameter does not match the actual resolution of
the current printer then you'll first be warned about possible scaling problems;
see page~\pageref{scaling-probs}.)
For example, if the current printer is a StyleWriter then you'll get a dialog
like this:

\vbox to 2.35in{\label{nonpsprint}\vfil
\noindent\hskip 0.65in\special{pntg=nonpsprint scale=0.72}}

\bigskip

\noindent
The dialog box lets you change various options specific to the current printer.
\OzTeX\ adds some extra items at the bottom of the dialog:
\begin{itemize}
\item
Some text showing the first and last DVI/\TeX\ pages.  This information can
be useful when entering DVI page numbers in the ``From'' and ``To'' edit boxes.
\item
Edit boxes for changing the page increment and DVI magnification.
\item
Check boxes for reversing the page order, showing statistics
and making missing PK fonts.
\end{itemize}
Click on the Print button or hit the Return key to start printing.
At any time while \OzTeX\ is printing you can switch to another application
and \OzTeX\ will continue to print in the background.

\subsubsection{Low-level PostScript printing}

If the current printer is a PostScript device
and ``Use Standard PostScript'' is \emph{not} ticked
then \OzTeX\ will open the DVI file and display the following dialog:

\vbox to 2.4in{\label{lowpsprint}\vfil
\noindent\hskip 1.0in\special{pntg=lowpsprint scale=0.72}}

\bigskip

\noindent
This dialog box lets you change a variety of print options.
Most of them should be fairly obvious; details can be found
in the description of ``Print DVI\,\ldots'' on page~\pageref{file-menu}.
The option you'll most often want to change is the page range.
The two scroll bars control the first and final pages.
\OzTeX\ prevents you from choosing a first page greater than the final page.
Play around with the scroll bars but restore their values so that every
page will be printed.
Click in the Print button or hit Return to start printing.

If the printer is found then a status box will appear and keep you
up-to-date on your job's progress and the state of the printer.
As each page is translated into PostScript its DVI/\TeX\ page
numbers are displayed in the \OzTeX\ window.

You can't actually print every page in \verb|nasty.dvi| because there
is a deliberate error that makes this impossible.
The first 11 pages should not cause any problems (assuming you're using
A4 paper) but the rest will generate nearly every type of error message
you're ever likely to encounter.
You should eventually get up to page~17 where a deliberate PostScript error
in a \verb|\special| file will prevent any further pages being printed.
(\OzTeX\ may start translating page~18 before the error is seen.)

The above dialog box also lets you send
the PostScript output to a file instead of the printer.
This file is an ordinary text file with a default name of \verb|nasty.ps|.
A warning: the PostScript code generated by \OzTeX\ is resolution-dependent.
If you send this code to a PostScript device with a resolution different
to that of the current printer resolution parameter
then the output might look a little strange.

A note for PostScript hackers: \OzTeX\ begins the PostScript output by
copying the contents of a file called \lowpro\ (kept in the \psfiles\ folder).
\OzTeX\ will also look for a file called \globalps\ in the current
folder and, if found, include its contents at the end of \lowpro.
For example, \globalps\ in the \psfiles\ folder shows how you can
get the word ``DRAFT'' printed in the background on every page.

\subsubsection{Standard PostScript printing}

If the current printer is a PostScript device
and ``Use Standard PostScript'' \emph{is} ticked
then \OzTeX\ will open the DVI file and display the standard dialog for that printer:

\vbox to 2.65in{\label{stdpsprint}\vfil
\noindent\hskip 0.6in\special{pntg=stdpsprint scale=0.72}}

\bigskip

\noindent
Below the normal options for the current printer, \OzTeX\ adds some extra items
(the same ones described under the dialog box for non-PostScript printing
on page~\pageref{nonpsprint}).
Click on the Print button or hit the Return key to start printing.

PostScript hackers should note that when standard PostScript printing
is used to print a DVI file, \OzTeX\ does \emph{not} use \lowpro;
instead it uses a file called \stdpro\ (also kept in the \psfiles\ folder).
The PostScript code in \stdpro\ is very similar to \lowpro, but there are
some subtle differences.  I decided it would be unsafe to allow
inclusion of a \globalps\ file when using standard PostScript, but I have
allowed for similar tricks by making \OzTeX\ look for \stdpro\ in the
current folder before looking in the PS folder(s).

Although there are significant advantages to using standard PostScript,
there are some disadvantages.  There is a limitation in LaserWriter print
drivers older than version~8 that causes a PostScript error when printing
all but the simplest of DVI files.  \OzTeX\ is able to predict when this
error is likely to occur and will display a suitable warning message.
Also, standard PostScript code takes longer to print and saved PostScript files
are a little bit larger.  If you want to use \OzTeX's more efficient
low-level printing code then leave ``Use Standard PostScript'' unticked.
Another advantage of low-level PostScript printing is that any PostScript
error messages will appear in the \OzTeX\ window
(although on some printers, like the LaserWriter Select 310, you might need to
send \verb|geterrors.ps| first).

In standard PostScript printing, \OzTeX\ has to go through all selected DVI pages
first and determine font and character usage.  All the PK character bitmaps used
in the document are then downloaded at the beginning, so the first page in a
long document might take some time to be printed.


\subsection{Positioning pages correctly}

For your DVI output to appear in precisely the right location on the paper,
the \TeX\ origin must be exactly one inch in from the top and left paper edges.
Page 2 in \verb|nasty.dvi| contains a thick rule with its top left
corner exactly at the \TeX\ origin.
If the printed page shows a significant discrepancy then adjust
the horizontal and vertical offsets in the {\tt Default} configuration file
to shift the origin to the correct position.

Note that if your printer is set up for US~Letter paper then before adjusting
the offsets you should first change the {\tt Default} file's paper width
to \verb|8.5in| and the paper height to \verb|11in|.

If you use more than one printer then you will probably need a separate
configuration file for each printer.
You might also need to create a separate configuration file for landscape printing.


\subsection{Continuing from where you left off}

That's the end of the guided tour.  One more useful feature to note is that
\OzTeX\ remembers most of your settings in a preferences file called \ozprefs.
Some of the important settings include window sizes and locations,
the \TeX\ file, the format, the DVI file
and the most recently previewed DVI page, including the scale and location
for use by the ``\verb|o|'' keyboard short cut.
The next time \OzTeX\ starts up it will recall
all this information so you can continue working from where you left off.
(Double-clicking on a file to start up \OzTeX\ will of course
override some of this information.)

If you want to restore all settings to their default values then simply
delete \ozprefs\ or move it into a folder where \OzTeX\ can't find it.
The next time \OzTeX\ starts up it will create a new \ozprefs\ file
and initialize it with default settings.

\ozprefs\ is created in the Preferences sub-folder under System~7
and later, or in the System folder itself in earlier System versions.
If you like, you can move \ozprefs\ to the same folder as \OzTeX;
I prefer this because it simplifies my backup process.

\newpage


\section{\OzTeX's menus}

Let's go through each menu and discuss each item in detail,
concentrating on the things not mentioned in the guided tour.


\subsection{The File menu}
\label{file-menu}

\subsubsection*{Print DVI\,\ldots}

Prints a selected DVI file.
After selecting the DVI file you'll be presented with a dialog box that
depends on the current printer and the settings of ``Use Standard PostScript''
and ``Use DVIPS'' (these flags are described later).
The dialog box for low-level PostScript printing (see page~\pageref{lowpsprint})
lets you change these printing options:
\begin{itemize}

\item
The page range.
The first and final pages are controlled by separate scroll bars; their
current values are displayed in the form ``DVI page/[\TeX\ page]''.

\item
The paper orientation (landscape or portrait).

\item
The page order (reverse or normal).

\item
Printer memory management (conserve VM or not).
VM is PostScript's ``virtual memory'' and the output generated by \OzTeX\ can
consume an awful lot of it, especially if your document uses a large number
of non-PostScript fonts.
If you get a ``\verb|VMerror|'' when printing a document then try again with
the conserve VM option checked.
You should only need to do this for a very unusual document,
like a font catalog.

\item
The paper source (manual feed or normal input tray).

\item
Whether or not to show statistics about font, rule and \verb|\special| usage.

\item
Whether or not to make missing PK fonts.

\item
The number of copies of each page.

\item
The page increment.
The primary purpose of this option is to simplify the printing of a document
on both sides of the paper.  If the first page is~1 and an increment
of~2 is chosen then \OzTeX\ will print pages 1, 3, 5, 7, etc.
Depending on how your printer stacks the output, you can then put these pages
back into the input tray and print the DVI file again using the same increment
but starting from the second DVI page
(and reversing the page order; this will not effect {\em which\/} pages
are printed but simply changes the {\em order\/} in which they are done).

\item
The DVI magnification
(expressed as an integer 1000 times the desired magnification).
You should use the default value unless you know what you're doing.
If the DVI file uses non-PostScript fonts then you should probably stick
to the numbers corresponding to \TeX's \verb|\magstep| values; i.e.,
1000, 1095, 1200, 1440, etc.
See Chapters~4 and 10 in \texbook\ for details.
A document using only PostScript fonts can be printed at almost any
magnification (\OzTeX\ allows values from 1 to 10000).

\end{itemize}
What happens next depends on which dialog button you select.
The default Print button will send the PostScript output to the current printer.
A status box will appear and indicate what is happening to your job and
warn you about any printer problems.
Or you might prefer to save the PostScript output to a given text file.
Any change to a check box option will be remembered the next time you
print a DVI file, unless you decide to Cancel the dialog.

The dialog boxes for standard PostScript printing (see page~\pageref{stdpsprint})
and non-PostScript printing (see page~\pageref{nonpsprint})
let you change various options specific to the current printer.
\OzTeX\ adds some extra items at the bottom of the dialog so you
can change the page increment or DVI magnification,
and decide whether or not to reverse the page order, show statistics,
or make missing PK fonts.

Regardless of which printing method \OzTeX\ decides to use, the messages
displayed in the \OzTeX\ window are almost identical.
The DVI/\TeX\ page numbers are displayed as each page is processed.
Any error messages or statistics apply to the most recently displayed
page numbers (although this is not true for messages sent back by a PostScript
printer because these occur asynchronously).
At any time you can hit Command-C or Command-Dot to cancel printing,
or you can switch to another application and \OzTeX\ will continue to print
in the background.

\subsubsection*{Print ?.dvi}

Prints the indicated DVI file.
You can print the file even after moving to another folder.
This item is initially disabled; the file name changes after you
select a DVI file via ``Print DVI\,\ldots'' or ``View DVI\,\ldots'',
or create a DVI file by running \TeX\null.

\subsubsection*{Print Text\,\ldots}

Prints a selected text file.
If \OzTeX\ decides to use low-level PostScript printing then
this file is sent after the \textpro\ file which is kept in the
\psfiles\ folder.  If you know a little about PostScript then
you might like to modify \textpro\ to suit your own needs.
For example, the tab width is defined in \textpro.

If \OzTeX\ uses standard PostScript printing, or non-PostScript printing,
then you'll get a printer-specific dialog with an extra edit box that
lets you specify the tab width.  The default tab width is 3; this is the value
used in various text files supplied with \OzTeX\null.
Text files are printed using 10\,pt Courier.

\subsubsection*{Page Setup\,\ldots}
\label{page-setup}

The ``Page Setup'' dialog lets you select various printer-specific options that
will be used in standard PostScript printing or non-PostScript printing.
If you select OK then the dialog settings are remembered for later \OzTeX\ sessions.
However, if the Chooser is used to select a different printer then the settings
will be restored to default values for the new printer.

Note that in low-level PostScript printing, \OzTeX\ ignores the ``Page Setup''
settings.  In this case the paper size is determined by config file parameters.

\subsubsection*{Use Standard PostScript}
\label{usestdps}

Tick this flag if you want to use the standard Mac print dialogs when printing
a DVI file or text file to a PostScript printer.  (However, if the currently
chosen printer is \emph{not} a PostScript device then \OzTeX\ ignores this flag
and switches to non-PostScript printing.)

If ``Use Standard PostScript'' is ticked, then remember that ``Page Setup''
must be used to select the paper size and orientation before printing
a DVI file or text file.  You can also select other handy features like
2-up printing if you have the LaserWriter~8 print driver.

\subsubsection*{Use DVIPS}
\label{usedvips}

This item is only enabled under System~7 or later.
Tick this flag if you want \OzTeX\ to call \dvips\ to translate a DVI file
into PostScript.  The top two items in the File menu change to
``DVIPS\,\ldots'' and ``DVIPS foo.dvi'' when ``Use DVIPS'' is ticked.
For more information about \dvips, see section~\ref{dv-sec}.

If ``Use DVIPS'' is ticked then \OzTeX\ ignores the ``Use Standard PostScript''
flag.  Of course, ``Use DVIPS'' is ignored when printing a text file.

\subsubsection*{Send PostScript\,\ldots}

Sends a selected text file, presumably a PostScript program, to the current
printer.  (If it isn't a PostScript printer then you won't get far!)
The \psfiles\ folder contains a number of interesting files that can be
sent to any PostScript printer.

If a PostScript file is sent to spooling software rather than directly to the
printer then you probably won't see any messages sent back to the \OzTeX\ window.
In such an environment it's a good idea to send \verb|errhandler.ps| first
so that any PostScript errors will be printed on paper.

\subsubsection*{Save \OzTeX\ Window\,\ldots}

Saves the contents of the \OzTeX\ window to a given text file.
The {\tt Default} config file sets the file name to \oztext.
This item is disabled if the \OzTeX\ window is empty or not the front window.

\subsubsection*{Quit}

Quits \OzTeX.


\subsection{The Edit menu}
\label{edit-menu}

\OzTeX\ does not have an integrated text editor, so the standard items
in this menu are normally disabled (although Cut/Copy/Paste/Clear
can be used in a dialog box with edit items).

\subsubsection*{Copy to Clipboard}

Copies the contents of the \OzTeX\ window to the Clipboard so you can paste
it into a text file.
This item is disabled if the \OzTeX\ window is empty or not the front window.

\subsubsection*{Font}

Selects the screen font used to display text in the \OzTeX\ window.
You can choose from any of the currently installed fonts, but for best
results it is advisable to use a fixed-width font like Monaco or Courier.
This item is disabled if the \OzTeX\ window is not the front window.

\subsubsection*{Size}

Selects the point size of the font used in the \OzTeX\ window.
(The available sizes are stored in a MENU resource in \OzTeX,
so use ResEdit if you want to change the supplied values.)
This item is disabled if the \OzTeX\ window is not the front window.

\subsubsection*{Choose Editor\,\ldots}

This item is only enabled under System~7 or later.
It lets you select the target application (presumably an editor) to which
\OzTeX\ will send ``open file'' events.  If the chosen application can
receive such events then \OzTeX\ remembers its name and location for later use
(as described below).

\subsubsection*{Select Error Line}

This item is only enabled under System~7 or later.
If ticked, this flag tells \OzTeX\ to include an extra parameter in the
``open file'' event sent when you type ``\verb|e|'' in response to
\TeX's ``\verb|?|'' prompt (which normally occurs after a \TeX\ error).
The extra parameter specifies the line number so your editor can
automatically select the line containing the error.
However, some editors can't handle the extra parameter and won't even open
the file.  You will need to experiment with your editor to see if it can
select the error line; if it can't then make sure ``Select Error Line'' is
\emph{not} ticked.  Note that \bbedit\ can't handle the extra parameter but the
full version of BBEdit can.  Recent versions of Alpha can.

\subsubsection*{Edit ?.tex}

This item is only enabled under System~7 or later.
If selected, \OzTeX\ will send an ``open file'' event to your current editor.
\OzTeX\ will launch the editor if necessary.
This item normally contains the name of the most recently typeset file
(it will always match the file shown in the \TeX\ menu's 2nd item).

\subsection{The \TeX\ menu}

\subsubsection*{\TeX\,\ldots}

Typesets a selected input file using the current format
(or the format in the corresponding log file if ``Use Format in Log''
is ticked; see below for more about this item).
The \OzTeX\ window acts like a terminal during a \TeX\ session.

One of the nicest things about \TeX\ is that it behaves the same way
on a large range of different computer systems.
Virtually everything you read in \texbook\ will apply to the version
of \TeX\ run by \OzTeX\ (and the same goes for Leslie Lamport's \LaTeX\ book
if you use that format).
Only a few special features have been added in \OzTeX:
\begin{itemize}

\item
Most of \TeX's capacity parameters are set at run-time in
a configuration file rather than at compile-time.
If you get a ``\TeX\ capacity exceeded'' error then
you should be able to overcome the problem by increasing the appropriate
parameter (see page~\pageref{capacity}).

\item
\TeX\ can be told to look in more than one folder when searching for
an input file or TFM file (by setting the appropriate config file parameters).

\item
You can interrupt a \TeX\ session at any time by typing
Command-C or Command-Dot.
Depending on what it is currently doing, \TeX\ usually responds immediately
with a suitable message and the ``\verb|?|'' prompt.
If you hit Command-C or Command-Dot at this stage
(or whenever the block cursor is visible) then \TeX\ will immediately abort.

\item
\TeX\ will continue typesetting in the background if you switch to another
application.

\end{itemize}

\subsubsection*{\TeX\ ?.tex}

Typesets the indicated input file using the current format
(or the format in the corresponding log file if ``Use Format in Log'' is ticked).
This item remembers the most recently typeset file.

\subsubsection*{Use Format in Log}

If this item is ticked, then before typesetting \verb|foo.tex| \OzTeX\ will look
in \verb|foo.log| to see which format should be used.
(In log files created by \OzTeX\ the format appears after the ``\&'' on line~2.)
If the log file exists and the format is known (i.e., exactly matches one of
the formats at the bottom of the \TeX\ menu) then \OzTeX\ automatically changes
the current format if necessary.  If the log file does not exist or does not
contain a known format then the current format will be used.
The state of ``Use Format in Log'' is remembered when you quit \OzTeX.

Note that if you manage to create a log file with a known but incorrect
format then you'll have to turn off ``Use Format in Log'' and manually select
the correct format before typesetting the corresponding input file.

\subsubsection*{Fix VFs in DVI\,\ldots}

Selects a DVI file and replaces all virtual font references with appropriate
characters and commands from actual fonts.
See section~\ref{vf-sec} for more information about virtual fonts.

\subsubsection*{Fix VFs after \TeX}

If this item is ticked then \OzTeX\ automatically fixes any virtual fonts
in the DVI file created at the end of a \TeX\ run.
The state of this flag is remembered when you quit \OzTeX.

\subsubsection*{INITEX}

Runs \initex, a special version of \TeX\ normally used to create format files;
see page~\pageref{fmt-sec}.

\subsubsection*{List of formats}

The items below \initex\ are read from the format list specified in
the most recently selected configuration file.
The {\tt Default} config file sets the format list to \LaTeX\ and Plain.

The current format is indicated by a tick and will be the one used when you
typeset a file (although this will be overridden if ``Use Format in Log''
is ticked and a log file exists).
To change the current format, simply select a different format item.
\OzTeX\ automatically ticks the first format found when loading a
configuration file, so it's a good idea to place your preferred format first.
Note that if a non-default configuration file uses the ``\verb|?|''
character to avoid changing the format list then \OzTeX\ won't change the
current format.


\subsection{The View menu}
\label{view-menu}

\subsubsection*{View DVI\,\ldots}

Previews a selected DVI file.
\OzTeX\ will open the view window and set its title to the name of the
selected DVI file.
You'll then be presented with a dialog box (see page~\pageref{viewdlg})
that lets you choose various viewing options:
\begin{itemize}

\item
The initial page to display.
A scroll bar allows you to locate any page in the DVI file.
The left and right arrow keys can be used to move the thumb box.
You can also type in a specific DVI page or \TeX\ page; if the given number
is valid then the other page number is updated and the scroll bar repositioned.
If there is only one page in the DVI file then the scroll bar will be inactive.

\item
The paper orientation (landscape or portrait).
Any change to this option will be remembered the next time you
view a DVI file, unless you Cancel the dialog.
The check box setting will also be used in the dialog for
low-level PostScript printing.

\item
Two more check boxes can be used to tell \OzTeX\ to ignore
bad \verb|\special| commands and/or missing fonts.
It is a good idea to select both these check boxes when previewing a DVI file
created by another \TeX\ system, otherwise you might get a lot of annoying
warning messages.  \OzTeX\ remembers these check box settings.

\item
The last check box can be used to make missing PK fonts
(but it will be ignored if ``Ignore missing fonts'' is selected).
\OzTeX\ remembers this check box setting.
See section~\ref{mf-sec} for more details.

\item
The DVI magnification.
You should only alter the default value if you plan to print the DVI file
at a different magnification.  See the description of ``Print DVI\,\ldots'' in
section~\ref{file-menu} for more details.
Note that \OzTeX\ does not remember any change to the DVI magnification.

\end{itemize}
If you Cancel the dialog then \OzTeX\ will close the view window.
If you select the View button then the current DVI/\TeX\ page numbers will be
appended to the DVI file name in the view window's title bar and
\OzTeX\ will locate the requested page, interpret it and display it.
You might have to wait a moment before seeing anything,
especially if it is a complicated page.

\OzTeX\ sets the initial scale factor and page location to values determined
by the default view (see section~\ref{def-view}).
However, if any part of the page is off the paper then \OzTeX\ will beep and
show a full view instead (see the ``Full View'' item below).

\subsubsection*{View ?.dvi}

Previews the indicated DVI file.
Exactly the same sequence of events described above will occur.
You can preview the file even after moving to another folder.
This item is initially disabled; the file name changes after you
select a DVI file via ``Print DVI\,\ldots'' or ``View DVI\,\ldots'',
and after \TeX\ creates a DVI file.

\subsubsection*{Show \OzTeX\ {\rm or} Show View}

Brings either the \OzTeX\ window or the view window (if open) to the front.
The Return key is a keyboard short cut for this menu item.

\subsubsection*{Page Info}

Displays information about the current DVI page in the \OzTeX\ window,
bringing it to the front if necessary.
This item is disabled if the view window is closed.
The information displayed includes:
\begin{itemize}
\item
The ten \TeX\ page counters stored with the current page (trailing
counters with zero values are not shown).
\item
The total number of pages, viewing resolution, DVI magnification and
paper dimensions.
\item
A list of all the fonts used in the entire DVI file.
For each font appearing on the current page \OzTeX\ will show the total number
of characters used.
Note that the order of fonts may change as you move from page to page;
\OzTeX\ sorts the list so that all fonts actually used on the current page
appear first.
A PostScript font is indicated by its corresponding TFM path name
and the requested point size.
A PK font is indicated by a PK path name.
Missing PK or TFM files are flagged by the message ``\verb|DOES NOT EXIST|''\null.
Missing screen fonts are flagged by the message ``\verb|NO SCREEN FONT|''.
\item
The number of rules on the page.
\item
The location and argument of each \verb|\special| command on the page.
The location is expressed in terms of \OzTeX's paper coordinate system;
see section~\ref{paper-coords}.
If the \verb|\special| command includes a valid PICT/PNTG/EPSF file then
the width and height of the image's bounding box is also displayed
(if there is an image).
\end{itemize}

\subsubsection*{Previous Page}

Displays the previous DVI page.
This item is disabled if the view window is closed or currently displaying
the first page.

\subsubsection*{Next Page}

Displays the next DVI page.
This item is disabled if the view window is closed or currently displaying
the last page.

\subsubsection*{Go to Page\,\ldots}

Brings up a dialog box allowing you to select any DVI page for display.
This item is disabled if the view window is closed or
if the DVI file only has one page.

\subsubsection*{Full View}

Changes the scale factor and location so that the entire DVI page and paper
edges are displayed in the middle of the current view window.
The scroll bars are disabled and the scale factor is set to its maximum value.
This item is disabled if the view window is closed or already displaying
a full view.

\subsubsection*{Actual Size}

Changes the scale factor so that the DVI page is displayed as near
as possible to its actual size.
The top left corner of the view window will still show the same page location,
unless shifting is necessary to keep within the scrolling limits.
This item is disabled if the view window is closed or already displaying
the page at its actual size.

The scale factor is actually set to the nearest integer equal to the viewing
resolution divided by the Mac screen resolution.
A likely calculation is $300/72 = 4.17$, so the scale factor is set to~4.
Because of this approximation, a 3\,in wide rule in your \TeX\ input file
won't appear exactly 3\,in wide in the view window.
If this is a serious problem then switch to a configuration file that sets
the viewing resolution to some multiple of the screen resolution;
you'll also need a matching set of PK files.
Note that $360 = 72 \times 5$.

\subsubsection*{Zoom In}

Halves the current scale factor.
The top left corner of the view window will still show the same page location,
unless shifting is necessary to keep within the scrolling limits.
This item is disabled if the view window is closed or already displaying
the page at minimum scale factor.

\subsubsection*{Zoom Out}

Doubles the current scale factor.
The top left corner of the view window will still show the same page location,
unless shifting is necessary to keep within the scrolling limits.
This item is disabled if the view window is closed or already displaying
the page at maximum scale factor.

\subsubsection*{Save as Default View}

Saves the current scale factor and page location as the default view
(see section~\ref{def-view}).
This item is disabled if the view window is closed.


\subsection{The Config menu}

\subsubsection*{Show}

Shows the current values of configuration parameters in the \OzTeX\ window.
You can choose to show all parameters or just some important subsets.
If you select ``All'' then the output is displayed with the correct syntax
for a configuration file; this makes it easy to create a new configuration
file by simply saving the \OzTeX\ window.

\subsubsection*{Load Config\,\ldots}

Lets you select and load a configuration file
(not necessarily in the \configs\ folder) without having to add it to the
list of configuration files in the {\tt Default} file.
This means you don't have to clutter up your Config menu with rarely used
config files.

\subsubsection*{Default}

Loads the {\tt Default} configuration file, resetting all parameters
to their default values.

\subsubsection*{Other configuration files}
\label{other-configs}

The remaining items in the Config menu are determined by information given in
the {\tt Default} configuration file.  The items must correspond to the
names of text files in the \configs\ folder.
Selecting one of these items causes the corresponding configuration file
to be loaded.  A tick appears next to the most recently loaded file.
Here is a brief description of all the non-default config files
supplied with \OzTeX:
\begin{description}

\item[\tt Big TeX] ---
Sets all the \TeX\ parameters to very large values.
It also sets the list of formats to Big-\LaTeX\ and Big-Plain.
See section~\ref{big-fmt} for more details.

\item[\tt StyleWriter] ---
Configures \OzTeX\ for the StyleWriter printer.
The printer and viewing resolutions are set to 360
and both \mf\ modes to {\tt stylewriter}.
The reverse page order parameter is set to {\tt true} because this printer
stacks pages face up.

\item[\tt ImageWriter] ---
Configures \OzTeX\ for the ImageWriter printer.
The printer and viewing resolutions are set to 144
and both \mf\ modes to {\tt imagewriter}.

\item[\tt Linotronic] ---
Configures \OzTeX\ for a Linotronic typesetter.
The printer resolution is set to 1270 and the mode to {\tt linohi}.
The viewing resolution and mode are not changed.

\item[\tt A5 Portrait] ---
Sets the paper dimensions for A5 paper in portrait mode.

\item[\tt A4 Landscape] ---
Sets the paper dimensions for A4 paper in landscape mode.

\item[\tt US Letter] ---
Sets the paper dimensions for US Letter paper in portrait mode.

\item[\tt View at 144 dpi] ---
Sets the viewing resolution to 144 and the mode to {\tt imagewriter}.
The printer resolution and mode are not changed.
Characters from 144\,dpi PK files scale better on most Mac screens
(normally 72\,dpi).  Previewing will also be faster and use much less memory.

\item[\tt View CM using PS] ---
Tells \OzTeX\ to preview Computer Modern text fonts using the nearest
``equivalent'' PostScript screen fonts.
If you have the corresponding TrueType or ATM (Adobe Type Manager) fonts,
your text will be much more readable, apart from some strange kerning
and the odd incorrect character (e.g., you won't see any ``ffi'' ligatures).
It is important to realise that this is a bit of a hack and
you should not try to print documents using this config file,
so remember to switch back to the {\tt Default} config file before printing.
The viewing resolution is set to 360 ($5 \times 72$) so that ``Actual Size''
dimensions will be accurate.

\item[\tt Add BaKoMa Fonts] ---
Updates the current list of PostScript fonts so that
\OzTeX\ can use the BaKoMa fonts created by Basil Malyshev.
These fonts are free PostScript and TrueType versions of Computer Modern.
They can be obtained by ftp from any CTAN site.
Get \verb|/tex-archive/fonts/cm/ps-type1/bakoma/mac/00readme.mac| first.

\item[\tt Add CM/PS Fonts] ---
Updates the current list of PostScript fonts so that
\OzTeX\ can use the CM/PS fonts available from Blue Sky Research.
The CM/PS fonts are PostScript versions of the Computer Modern fonts.
The screen fonts provide a much more readable preview.

\item[\tt Add Lucida Fonts] ---
Updates the current list of PostScript fonts so that
\OzTeX\ can use the Lucida fonts available from Y\&Y\null.
Lucida is an alternative to Computer Modern, including math fonts, in
Adobe Type~1 format.

\item[\tt Add MathTime Fonts] ---
Updates the current list of PostScript fonts so that
\OzTeX\ can use the MathTime fonts available from The \TeX plorators Corporation.
MathTime is a set of math fonts suitable for use with Times Roman.

NOTE: Before using any of the above four config files   % XREF
you might need to change the path name that tells \OzTeX\ where to find
the font files that must be downloaded when printing to a PostScript device.
These files are normally kept in the Fonts sub-folder of your
System folder in System~7.1, or in the Extensions sub-folder in System~7.0.
\OzTeX\ doesn't really care where you keep them, but it does need to be
told where to find them.

\end{description}
Some config files do not appear in the Config menu but can be
loaded from the \configs\ folder:
\begin{description}

\item[\tt Remove Help Menu] ---
Removes \OzTeX's Help menu.

\item[\tt Old LaTeX] ---
Configures \OzTeX\ to typeset with the old \LaTeX\,2.09 format;
see section~\ref{oldlatex}.

\item[\tt New LaTeX] ---
Configures \OzTeX\ to typeset with the new \LaTeX\ format;
see section~\ref{oldlatex}.

\end{description}
You can of course modify any of these config files to suit your own needs.
If you've created your own config files and you think other people
might find them useful, please e-mail them to me and I'll
add them to the standard \OzTeX\ distribution.


\subsection{The Help menu}

The items appearing in this menu are read from the help list in a configuration
file and must correspond to the names of text files in the \helpfiles\ folder.
Selecting an item from the Help menu simply causes the contents of the
corresponding file to appear in the \OzTeX\ window.

Feel free to add more items to the Help menu.
For example, you might like to create a file of \TeX/\LaTeX\ commands to refer
to while editing an input file.
If you want to add more help files, or modify the existing ones, then there
are a few things to watch out for.
Don't use tabs, and avoid long lines if you have a small screen.
If you create a new help file then remember to update
the {\tt Default} configuration file.

\newpage


\section{\LaTeX}

\OzTeX\ is distributed with the latest implementation of \LaTeX\ (formerly
called \LaTeX\,2e).  This new version of \LaTeX\ is described in
the 2nd edition of {\sl \LaTeX: A Document Preparation System\/} by Leslie Lamport
and {\sl The \LaTeX\ Companion\/} by Michel Goossens, Frank Mittelbach and
Alexander Samarin.  Both books are published by Addison-Wesley.

A number of important \LaTeX\ packages are provided.
The \verb|psnfss| package makes it easy to switch to PostScript text fonts
instead of Computer Modern.
The \verb|graphics| package makes it easy to include Macintosh graphic files.
See the documentation and test files in the
\verb|PSNFSS| and \verb|Graphics| sub-folders in \texinputs.
Other common packages are kept in the \verb|Tools| sub-folder.
More information about \LaTeX\ can be found in the {\tt .tex} files
in the \verb|LaTeX| sub-folder.

The \LaTeX\ system included with \OzTeX\ is \emph{not} a full distribution
(which is way too big for most \OzTeX\ users).
After installing the base files and the above packages,   % XREF
I deleted all the {\tt .dtx}, {\tt .ins} and {\tt .fdd} files,
as well as a few other files that were irrelevant for \OzTeX\ users.
If you need a file or package not provided in \OzTeX, then you can ftp it
from any CTAN site or mirror.  The following table should help:
\begin{tabbing}
\indent \= Sub-folder in \texinputs\qquad \= \kill
\> Sub-folder in \texinputs  \> Corresponding CTAN directory\\ [6pt]
\> {\tt LaTeX}               \> {\tt /tex-archive/macros/latex/unpacked}\\
\> {\tt Graphics}            \> {\tt /tex-archive/macros/latex/packages/graphics}\\
\> {\tt PSNFSS}              \> {\tt /tex-archive/macros/latex/packages/psnfss}\\
\> {\tt Tools}               \> {\tt /tex-archive/macros/latex/packages/tools}
\end{tabbing}
If you only need one or two files then ask me first and I might have a
copy I can send by e-mail, but you must be a registered \OzTeX\ user!


\subsection{Using \LaTeX\,2.09}
\label{oldlatex}

The old \LaTeX\,2.09 system is no longer distributed with \OzTeX\null.
\LaTeX\ users should seriously consider switching to the new \LaTeX; it can
typeset \LaTeX\,2.09 documents in ``compatibility'' mode.  If you have the
old \LaTeX\ system from an earlier version of \OzTeX\ and you want to use
it alongside the new \LaTeX, then carry out these steps:
\begin{enumerate}

\item
Delete all log files for your existing \LaTeX\ documents so that
\OzTeX\ won't get the wrong format by looking in a log file.

\item
Edit the {\tt Default} config file and insert
\verb|"New LaTeX"| and \verb|"Old LaTeX"| anywhere in the list of config files.

\item
Take the {\tt LaTeX} sub-folder out of your \emph{old} \texinputs\ folder,
rename it {\tt Old LaTeX} and put it next to (\emph{not} inside) the new
\texinputs\ folder.
If you want to store the {\tt Old LaTeX} folder somewhere else,
or use a different name, then you'll have to change the appropriate path in the
{\tt Old LaTeX} config file.

\item
Build {\tt OldLaTeX.fmt} (no space in the file name!):
\begin{enumerate}
\item Start up \OzTeX\ and select {\tt Old LaTeX} from the Config menu.
\item Run \initex, type ``\verb|lplain\dump|'' and hit Return.
\item Save the format as {\tt OldLaTeX.fmt} in the \texformats\ folder.
\end{enumerate}

\end{enumerate}
Before typesetting a \LaTeX\,2.09 document you must remember to select
{\tt Old LaTeX} from the Config menu, and before typesetting a new
\LaTeX\ document you must select {\tt New LaTeX}.


\section{Building format files}
\label{fmt-sec}

A format file contains a pre-compiled set of macros which \TeX\ can load in
very quickly.
To build a format file you need to run \initex\ (in the \TeX\ menu).
You may need to rebuild all format files if you edit a configuration file and
change certain \TeX\ parameters to suit your typesetting needs or your
Mac's memory capacity.  Building a format file is quite easy;
here are the steps used to create \verb|Plain.fmt|:
\begin{enumerate}
\item
Run \initex, wait for the ``\verb|**|'' prompt, type ``\verb|Plain\dump|''
and hit the Return key.
\initex\ will begin reading \verb|plain.tex| from the \verb|Plain| sub-folder
in \texinputs.
\item
You'll eventually get a standard dialog box allowing you to save the format
information in the file and folder of your choice.
The default file shown will be \verb|Plain.fmt|.
The best location for format files is the \texformats\ folder.
\item
Note that {\tt Plain.log} is created in the current folder.
It's not needed, so delete it.
\end{enumerate}
The steps needed to create \verb|LaTeX.fmt| are very similar:
\begin{enumerate}
\item
Run \initex, wait for the ``\verb|**|'' prompt, type ``\verb|LaTeX.ltx|''
and hit Return (you don't need to add \verb|\dump|).
\initex\ will read \verb|latex.ltx| from the \verb|LaTeX| sub-folder
in \texinputs.
\item
The dialog box will show \verb|LaTeX.fmt|, so just save this
file in the \texformats\ folder.
\item
Delete {\tt LaTeX.log} if you want to.
\end{enumerate}
If you decide to rename one of the existing formats,
or add a completely new format,
then remember to update your configuration file(s).

\subsection{Building big formats}
\label{big-fmt}

Some people with very large or complicated documents will need to build
big versions of the Plain or \LaTeX\ formats.  Here's how:
\begin{enumerate}
\item
Read the comments at the top of the {\tt Big TeX} configuration file.
It sets most of the \TeX\ parameters to very large values, but you may
want to increase or reduce them depending on how much memory you have.
It also sets the list of formats in the \TeX\ menu to \hbox{Big-\LaTeX} and
Big-Plain.  You can change these to anything you like; just make sure
your format names don't contain any spaces.
\item
After making any changes to {\tt Big TeX}, click on the \OzTeX\ icon
and use ``Get Info'' in the Finder's File menu to set \OzTeX's preferred
memory size to a suitable value (use 3100K if you didn't make any changes).
\item
Restart \OzTeX\ and select {\tt Big TeX} from the Config menu.
\item
Run \initex\ and type in the appropriate string for the desired format:
``\verb|Plain\dump|'' for Big-Plain or
``\verb|LaTeX.ltx|'' for Big-\LaTeX.
\item
When the dialog box appears, change the format file name to match the
name listed in {\tt Big TeX} ({\tt Big-Plain.fmt} or {\tt Big-LaTeX.fmt})
and save the file in the \texformats\ folder.
\item
Delete the log files if you don't want to keep them.
\end{enumerate}
When you want to use a big format, select {\tt Big TeX} from the
Config menu first, then select the desired format from the \TeX\ menu.
If you'll be using big formats all the time then you should
copy the parameter settings from {\tt Big TeX} into the {\tt Default}
configuration file and remove {\tt Big TeX} from the config file list.


\section{Fonts}

\OzTeX\ can use the following sources of font information in the
process of typesetting, previewing and printing a document:
TFM files, PK files, VF files, PostScript font files
(for downloading non-resident fonts) and Macintosh screen fonts.
The following sub-sections discuss all these font sources in some detail.


\subsection{TFM files}
\label{tfm-sec}

A \TeX\ Font Metric file contains the crucial typesetting information for
a font, such as each character's height, depth and width.
The actual character images are not stored in a TFM file.
TFM files are the only source of font information used when running \TeX;
it doesn't need to know anything about character images to be able
to create a DVI file.
See \texbook\ if you want to know more about how
\TeX\ uses fonts, especially Chapter~4 and Appendix~F.

\OzTeX\ reads TFM files when printing or viewing a DVI file
containing any of the fonts listed at the end of your configuration file.
The dummy TFM file specified in your configuration file will also be read
if a requested PK file can't be found
(PK files are discussed in section~\ref{pk-sec}).

\OzTeX\ will look for a TFM file in the current folder before looking in
the sub-folders in \texfonts.
All the TFM files in the \verb|CM| sub-folder belong to the
Computer Modern family of fonts (created by Donald Knuth using \mf\null).
The TFM files in the \verb|LaTeX| sub-folder are used by \LaTeX\null.
The TFM files in the \verb|PS| sub-folder correspond to PostScript fonts;
their names follow a scheme devised by Karl Berry in an attempt
to make \TeX\ input files more portable.  See section~\ref{ps-fonts} for
more information about these PostScript fonts.


\subsection{Creating new TFM files}
\label{new-tfm}

If the \OzTeX\ distribution doesn't provide a TFM file for a font you
would like to use then there are a number of things you can do:
\begin{enumerate}

\item
If you have access to the Internet then look for the TFM file in the
nearest CTAN site (see the ``Related Software'' item in the Help menu).
If the font is called \verb|foo| then look for \verb|foo.tfm|.
If it is a PostScript font then you might have to search a bit harder;
using Karl Berry's scheme it might be called something like \verb|pfo.tfm|.
If you find it, remember that a TFM file must be transferred as a binary file.

\item
If you can't find \verb|foo.tfm| then look for \verb|foo.mf|.
Such a file can be used by \mf\ to create \verb|foo.tfm|
(and a corresponding set of PK files at any resolution you like).
See section~\ref{mf-sec}.

\item
If \verb|foo| is a PostScript font then look for \verb|foo.afm|.
An AFM (Adobe Font Metric) file contains very similar information to a TFM file.
Alan Jeffrey's \verb|fontinst| package can convert an AFM file
into a PL or VPL file which \OzTools\ can then convert into a TFM file
(see page~\pageref{oztools}).

\item
As a last resort you could even create a PL file from scratch.
A very tedious and error-prone job though.

\end{enumerate}
Having found or created a new TFM file, you need to place it in a suitable
folder so that \OzTeX\ can find it.  If you put it in one of the sub-folders
in \texfonts\ (or create a new sub-folder) then you won't need to change the
TFM folder(s) in the {\tt Default} config file.

If the TFM file is for a PostScript font then you must add a suitable
entry to the list of fonts at the bottom of the {\tt Default} config file.
The examples in the file will show you what to do.

\subsection{PK files}
\label{pk-sec}

PK (packed pixel) files store the character images needed to print or view
a DVI file containing fonts \emph{not} listed at the end of your configuration file.
For each such font there is usually a number of PK files, each one
representing the same font but at a different size.
This size (which has no relation to the font's design size) is calculated
as follows:
$$
\hbox{\sl size} = \hbox{\sl resolution} \times \hbox{\sl magnification}
$$
where {\sl resolution\/} is either the printer resolution or the
viewing resolution, and {\sl magnification\/} is the overall font magnification
(i.e., the DVI magnification times the individual font scaling).
The {\sl size\/} is then rounded up to the nearest integer and should
equal ($\pm 1$) one of the folder names in \pkfiles\ if you decide to keep
PK files of the same size in separate folders.

Although \TeX\ allows you to request a font at virtually any magnification,
it is obviously impossible to provide an infinite number of PK files.
The compromise solution is to provide a range of sizes for each font.
These sizes are in a geometric ratio based on powers of 1.2 and correspond to
\TeX's \verb|\magstep| values.
See Chapters~4 and 10 of \texbook\ for more details.
For example, assuming a {\sl resolution\/} of 300 and no document magnification:
\begin{tabbing}
\indent \= \verb|\font\rb=cmr10 scaled\magstephalf|\qquad \= $1.5\times1.2^{0.5}$\qquad \=\kill
\> \TeX\ input                             \> {\sl size}          \> PK file\\ [6pt]
\> \verb|\font\ra=cmr10|                   \> $300\times1.2^0$    \> \verb|cmr10.300pk|\\
\> \verb|\font\rb=cmr10 scaled\magstephalf|\> $300\times1.2^{0.5}$\> \verb|cmr10.329pk|\\
\> \verb|\font\rc=cmr10 scaled\magstep1|   \> $300\times1.2^1$    \> \verb|cmr10.360pk|\\
\> \verb|\font\rd=cmr10 scaled\magstep2|   \> $300\times1.2^2$    \> \verb|cmr10.432pk|\\
\> \verb|\font\re=cmr10 scaled\magstep3|   \> $300\times1.2^3$    \> \verb|cmr10.518pk|\\
\> \verb|\font\rf=cmr10 scaled\magstep4|   \> $300\times1.2^4$    \> \verb|cmr10.622pk|\\
\> \verb|\font\rg=cmr10 scaled\magstep5|   \> $300\times1.2^5$    \> \verb|cmr10.746pk|
\end{tabbing}
\TeX's \verb|\magnification| command has a cumulative effect on font scaling:
\begin{verbatim}
   \magnification=\magstep1            % document magnification = 1.2
   \font\bigrm=cmr10 scaled\magstep2   % font magnification = 1.44
\end{verbatim}
The font size is now $ 300 \times 1.2 \times 1.44 = 518.4 $,
so \OzTeX\ will use \verb|cmr10.518pk|.
Note that \LaTeX\ has no \verb|\magnification| command --- use
the \verb|11pt| and \verb|12pt| options to increase the size
of all fonts in a \LaTeX\ document.

For compatibility with other \TeX\ systems, \OzTeX\ uses a fairly
complicated search scheme when looking for a font file.
If \verb|foo| is a PostScript font then \OzTeX\ looks for \verb|foo.tfm| in the
current folder before looking in \texfonts.
If \verb|foo| is not a PostScript font then \OzTeX\ looks for a PK file at the
requested size.  For example, if the calculated size is 300 then \OzTeX\ will
look for:
\begin{tabbing}
\indent \= 1. \verb|:PK-files:300:foo.300pk|\qquad \=\kill
\> 1. \verb|foo.300pk|               \> (in the current folder)\\
\> 2. \verb|:PK-files:300:foo|       \> (relative to the location of \OzTeX)\\
\> 3. \verb|:PK-files:300:foo.300pk| \> (ditto)\\
\> 4. \verb|:PK-files:foo.300pk|     \> (ditto)
\end{tabbing}
In fact, at each step \OzTeX\ will also add and subtract 1 from 300
because rounding errors can occur in the size calculation.
If still not found, \OzTeX\ gives up and displays a warning.

There is still another possibility to consider: a font name can include
an explicit location.  For example, your \TeX\ input file might contain
\verb|\font\xxx=:myfonts:foo|.  In this case \TeX\ will look for
\verb|:myfonts:foo.tfm| in the current folder;
that is, it expects to find a file called \verb|foo.tfm|
in a sub-folder called \verb|myfonts|.
If not found then it gives up; it does not look for \verb|foo.tfm| in \texfonts.
Similarly, when you print or view the DVI file, \OzTeX\ will only look for
\verb|:myfonts:foo.tfm| if \verb|foo| is a PostScript font,
or for \verb|:myfonts:foo.300pk| (or \verb|301pk| or \verb|299pk|)
if \verb|foo| is a PK font.
Note that the use of an explicit font location is not recommended as it
decreases the portability of your \TeX\ input file.

Most of the PK files supplied with \OzTeX\ have been specifically generated
for a 300\,dpi, write-black laser printer (like the Apple LaserWriter).
If your printer doesn't have the same characteristics then you might need
to get the correct PK files from some other source.
Or build them yourself using \mf\ as described in section~\ref{mf-sec}.

Note that the 300\,dpi PK files supplied with \OzTeX\ can also be used
on a 360\,dpi printer like the StyleWriter (because $360 = 300 \times 1.2$).
Two sub-folders, \verb|394| and \verb|896|, complete the standard set of
magnifications for a 360\,dpi printer:
394 is the nearest integer to $360 \times 1.2^{0.5}$ and 
896 is the nearest integer to $360 \times 1.2^5$.


\subsection{PostScript fonts}
\label{ps-fonts}

To be able to view or print a PostScript font in a \TeX\ document,
\OzTeX\ needs to know certain information about the font,
especially the name of its corresponding TFM file.
This information is specified at the end of a configuration file
(see the {\tt Default} file).

The PostScript TFMs stored in the \verb|PS| sub-folder in \texfonts\ are
meant to be used in conjunction with the virtual font files
stored in the \vffiles\ folder
(section~\ref{vf-sec} has more information about virtual fonts).
These TFMs and VFs were created for the \verb|psnfss| package
by Sebastian Rahtz using Alan Jeffrey's \verb|fontinst| macros.
The fonts are supplied in both OT1 and T1 encodings.
The default encoding is OT1; this is the old \TeX\ text font encoding
described in \texbook.
The T1 (or Cork) encoding is the new \TeX\ text font encoding for
256-character fonts.  The T1 TFMs and VFs have names ending in ``q''.
See \verb|test0.tex| in the \verb|PSNFSS| sub-folder in \texinputs\ for
how to select either encoding.

Virtual PostScript fonts like \verb|ptmr| should not appear in a
config file's list of PostScript fonts.
Only the corresponding ``raw'' font (\verb|ptmr0|) should be listed.
Note that raw TFMs are indicated by names of the form \verb|*0.tfm|.
When \OzTeX\ is fixing VFs it will replace characters from \verb|ptmrq.tfm|
with characters from \verb|ptmr0.tfm| according to the mapping defined
in \verb|ptmrq.vf|.

Every PostScript printer has a certain set of resident fonts.
To see an alphabetical list of the PostScript fonts available in your current
printer, choose ``Send PostScript\,\ldots'' from the File menu,
open the \psfiles\ folder, and send the file \verb|getfonts.ps|.
The list should appear in the \OzTeX\ window.
If you'd prefer to print the list then send \verb|fontlist.ps|.

The font you wish to use may not reside in the current printer, so
\OzTeX\ provides a mechanism for downloading non-resident PostScript fonts.
For example, the following entry appears in the list of PostScript fonts at
the bottom of the {\tt Default} file:
\begin{verbatim}
   =   putr0   Utopia-Regular  <putr.pfa   Utopia   Mac.enc
\end{verbatim}
The file to be downloaded appears immediately after the ``\verb|<|'' character.
When \OzTeX\ translates a DVI file into PostScript, it checks if any
fonts need to be downloaded.  If \verb|putr0| is used on a selected page then
the above entry tells \OzTeX\ to include \verb|putr.pfa| in the PostScript output.
\OzTeX\ looks for \verb|putr.pfa| in the current folder first and then
in the PS folder(s).

\OzTeX\ can also download font information stored in a Macintosh-specific
PostScript font file.
It checks the type of the file specified after ``\verb|<|'' and
if the type is LWFN then it will download the PostScript code stored in
the file's POST resources.  Such files are normally kept somewhere in your
System folder (e.g., in the Fonts sub-folder under System~7.1), so you will
need to add a suitable path to the PS folder(s) in the {\tt Default} config file.

To print a DVI file that uses PostScript fonts on a non-PostScript printer
you should have the corresponding screen fonts installed in your system.
For example, if \verb|putr0| appears in the DVI file then \OzTeX\ will try to
use the screen font \verb|Utopia|.
If \verb|Utopia| is not installed then \OzTeX\ will display an error message
and use the system font instead (normally Chicago).
When previewing a DVI file, \OzTeX\ will also warn you if it can't find the
screen font for a PostScript font; all characters from such a font will be
shown using the system font in the missing font colour.

There are some important differences between PostScript fonts and
the Computer Modern fonts created specifically for use with \TeX:
\begin{enumerate}

\item
A PostScript font can be requested at almost any size.
For example, in Plain \TeX\ you can do things like
``\verb|\font\helv=phvr at 33.3pt|''.

\item
When a PostScript font is scaled to the same design size as a CM font
it tends to look darker and larger.  It is probably not a good idea
to use the two font designs in the same document.

\item
The standard \TeX\ commands for accents and foreign letters need to be
redefined for a PostScript text font.
For Plain \TeX\ users, the file \verb|pstext.tex| in the \verb|Plain| sub-folder
in \texinputs\ contains the required macro definitions.
Another file, \verb|psfonts.tex| in \texdocs, inputs these macros and
illustrates the use (and abuse) of PostScript fonts in a Plain \TeX\ document.

\end{enumerate}
\LaTeX\ users can typeset a document with PostScript text fonts rather
than Computer Modern by simply adding a suitable package declaration.
For example,
\begin{verbatim}
   \documentclass{article}
   \usepackage{times}
\end{verbatim}
will switch the default text font to Times-Roman.  See the documentation in
the \verb|PSNFSS| sub-folder in \texinputs\ for other possibilities.
Note that CM math fonts will still be needed to typeset mathematics, but you
can buy commercial font packages such as Lucida or MathTime that include
PostScript replacements for these math fonts.
Another alternative is to get the BaKoMa or CM/PS fonts;
these are PostScript versions of the Computer Modern fonts.
\OzTeX\ provides configuration files for switching to BaKoMa, CM/PS,
Lucida or MathTime.


\subsection{Macintosh screen fonts}

The fonts listed at the end of a configuration file are not restricted to
PostScript fonts.
The list is really for any non-PK font, and that could be an outline font
in TrueType format, or even some sort of bitmap font in non-PK format.
The critical requirement is that a matching TFM file exists so that
\TeX\ can typeset characters from that font.

When previewing a DVI file containing a non-PK font
(or when printing such a file on a non-PostScript printer),
\OzTeX\ draws characters using the corresponding Macintosh screen font
given in the config file.  If the requested screen font can't be found then 
\OzTeX\ will warn you and use the system font instead.
If you want to use PostScript fonts with \OzTeX\ then for best results
you should get the TrueType or ATM versions of the screen fonts listed
in the {\tt Default} config file.

\newpage


\subsection{Encoding files}
\label{enc-sec}

Encoding files give you complete control over which Macintosh character
is displayed when a particular PostScript character in a DVI file is
to be viewed or printed on a non-PostScript printer
(encoding files are \emph{not} used during either low-level or standard
PostScript printing).

Encoding files are loaded at the time a configuration file is loaded.
Every PostScript screen font must be followed by an encoding entry
which is either the name of an existing encoding file, or \verb|nil| if the
screen font uses the same encoding as its corresponding TFM file.
\OzTeX\ looks for a given encoding file in the current PS folder(s)
and, if found, uses it to build an encoding array of 256 elements.
This array defines the mapping of DVI character codes into Macintosh characters.
You can see the currently loaded encoding arrays by selecting the appropriate
sub-item in the Config menu's ``Show'' item.

The syntax of an encoding file is described in detail in the standard encoding
file called \stdenc\ which is kept in the \encfiles\ sub-folder in \psfiles.
This encoding file maps characters from a standard PostScript text font
into equivalent characters in a standard Macintosh text font.
Depending on the encoding scheme used in your PostScript TFMs or screen fonts,
you might need to create other encoding files.
For an interesting example of how such files can be used,
see the \verb|View CM using PS| configuration file.


\subsection{Virtual fonts}
\label{vf-sec}

Virtual fonts provide a convenient and flexible way to specify a
mapping from \TeX's notion of a font character to the
capabilities of a particular output device (e.g., screen or printer).
In particular, virtual fonts make it easy to use PostScript fonts with \TeX.
The definitive document on virtual fonts is Donald Knuth's article
in TUGboat vol.~11 no.~1.  A text version called \verb|knuth-vf|
can be found in the \texdocs\ folder.

\OzTeX\ supports virtual fonts via two items in the \TeX\ menu:
``Fix VFs in DVI'' can be used to select a DVI file and replace all
virtual font characters with appropriate characters from actual fonts
(or with the specified rules and other DVI commands allowed in VF files).
The code used to perform this task is based on Peter Breitenlohner's
{\tt DVIcopy} program.

Another item, ``Fix VFs after \TeX'', can be ticked to tell \OzTeX\ to
automatically fix any VFs in the DVI file created at the end of a \TeX\ run.
This means you don't have to remember to run ``Fix VFs in DVI'' before
viewing or printing a DVI file that contains virtual fonts.

If you intend to make frequent use of virtual fonts then it would be
a good idea to tick ``Fix VFs after \TeX''\null.
Even if you only use virtual fonts rarely, it doesn't hurt to tick this option.
\OzTeX\ can quickly check to see if any virtual fonts are used in a DVI file;
if none are used then no further processing is carried out.
To decide if font \verb|foo| is virtual or not, \OzTeX\ looks for a file called
\verb|foo.vf| in the \vffiles\ folder.

If one or more virtual fonts are used then \OzTeX\ reads the entire DVI file,
creates a new DVI file with no virtual font references, deletes the original
DVI file and renames the new file with the original name.
If an error is detected, or if you decide to cancel processing, \OzTeX\ will
delete the new file and leave the original file untouched.

\newpage


\section{\OzTools}
\label{oztools}

\OzTools\ is a companion program for \OzTeX\ which includes the
following \TeX-related tools:
\begin{description}

\item[\tt TFtoPL] ---
Converts a TFM (\TeX\ font metric) file into a PL (property list) file.
The PL file will be created in the current folder;
it is a human-readable version of the information stored in the TFM file.
Apart from verifying the correctness of a TFM file, {\tt TFtoPL} can also be
used to modify the font metrics.  For example, you can edit the PL file,
change the amount of kerning between two characters, and run {\tt PLtoTF}.

\item[\tt PLtoTF] ---
Converts a PL file into a TFM file.
The TFM file will be created in the current folder.

\item[\tt VFtoVP] ---
Converts a VF (virtual font) file into a VPL (virtual property list) file.
The VPL file will be created in the current folder;
it is a human-readable version of the information stored in the VF file.
{\tt VFtoVP} also needs to read one or more TFM files
from the folder path specified in the ``Set TFM folder'' dialog.
(If you keep the \OzTools\ application in the same folder as the
\texfonts\ folder then you won't need to change the supplied path.
Note that multiple search folders are not supported, so it's a good idea
to keep all VF-related TFMs in the one folder.
All of \OzTeX's VF-related TFMs are currently kept in the {\tt PS} sub-folder
in \texfonts.)

\item[\tt VPtoVF] ---
Converts a VPL file into a VF file.
The VF file will be created in the current folder.
{\tt VPtoVF} also creates a new TFM file in the folder specified by the
``Set TFM folder'' dialog.

\end{description}
\OzTools\ provides some nice features for running these tools in a Mac
environment.  For example, the standard file dialog has a ``Do all files''
button which allows you to process all TFM/PL/VF/VPL files in the current folder.
Background processing is supported.
You can also delete PL/VPL files from within \OzTools.


\section{Transferring TFM/VF/PK/DVI files}

\OzTeX\ reads standard TFM/VF/PK files,
and reads and writes standard DVI files.
If you have access to \TeX\ on some other computer system, you should be able
to move such files to and fro without any further processing.

For the purposes of data transmission a TFM/VF/PK/DVI file must be treated as
a binary file (a stream of arbitrary 8-bit bytes).
When using Kermit to transfer binary files from another computer to your Mac,
remember to type ``\verb|set file type binary|'' before using
the \verb|send| command.
The same goes for receiving such files from your Mac, but with one exception:
to transfer a DVI file created by \OzTeX\ to a VAX/VMS host you'll need to
type ``\verb|set file type fixed|'' before using the \verb|receive| command.

If you have access to the Internet then there is a huge library of
TFM/VF/PK files available by anonymous ftp from many archive sites.
When using ftp to transfer such files, remember to type the
``\verb|binary|'' command before using ``\verb|get|''.

If you transfer a DVI file to your Mac and a mistake occurs during transmission,
or if you forgot to send it as a binary file, then \OzTeX\ will display
some sort of error message soon after opening the file.

Note that a DVI file contains TFM file names;
this can be a cause for concern if you plan to transfer DVI files from one
\TeX\ system to another system with a different set of TFM files.
Another cause of portability problems are \verb|\special| commands.
If you have a choice, it's always safer to transfer the original \TeX\ input
file so you can edit any incompatible font names or \verb|\special| commands.


\section{Including graphics}
\label{graphics}

Creating figures and illustrations with \TeX\ isn't easy.
Although it is theoretically possible to place small dots
anywhere on a page and build up an arbitrarily complex picture,
time and memory limitations make such a scheme impractical.
(\LaTeX\ provides a \verb|picture| environment, but it is very inefficient
and only suitable for small, simple diagrams.)

\TeX\ does however provide a \verb|\special| command which can be used
to pass arbitrary information to the DVI interpreter.
\OzTeX's printing and previewing code interprets a \verb|\special| command
using a simple syntax that allows inclusion of a given file.

Note that using \verb|\special| can seriously reduce the portability of
your \TeX\ documents because a given DVI-reading program can only understand
\verb|\special| commands that obey its own particular syntax.
One useful technique to enhance portability is to
hide the actual \verb|\special| call inside a macro; then when you move your
\TeX\ file to another computer all you need to do is change the macro
definition (assuming the DVI driver supports similar functionality in its
handling of \verb|\special|).
For an example of this approach see Larry Siebenmann's
\verb|boxedeps.doc| and \verb|boxedeps.tex| in the \verb|Plain| sub-folder
in \texinputs.
Another alternative is \verb|epsf.tex|; see \verb|epsftest.tex| in the
\texdocs\ folder.  Using either of these macro packages will make your
input files much more portable.

A \verb|\special| command can appear almost anywhere in your input file.
It behaves like an invisible box of zero height and width.
\TeX\ simply stores the given information in the DVI file at the current
page position.
When previewing a DVI file, \OzTeX\ draws a small marker indicating the
location of a \verb|\special|.
The ``Page Info'' item will display this location in paper coordinates
as well as the text of the \verb|\special| command.
Similar information is displayed if you choose to show statistics
when printing a DVI file.


\subsection{Including Macintosh graphic files}

\OzTeX\ allows the inclusion of three common types of Macintosh
graphic files:
\begin{itemize}

\item
PICT files can be generated by almost all drawing/painting programs
on the Macintosh.  A quick way to get a PICT file if you're using System~7
is to type Shift-Command-3.
To include a PICT file, use a command of the form:

\verb|\special{pict=filename}|

Note that \OzTeX\ converts the PICT file into a black and white bitmap
for previewing and printing, so you won't see any colours.
The bitmap is always at 72\,dpi when previewing, but the current
printer resolution is used when printing.

\item
PNTG files are also very common --- they're better known as MacPaint files.
(Shift-Command-3 on a Mac running System~6 or earlier will create a screen
dump in a file of type PNTG\null.  If you have a colour monitor you'll
first need to set it to black and white.)
To include a PNTG file, use a command of the form:

\verb|\special{pntg=filename}|

\item
EPSF files are becoming increasingly common.
They contain encapsulated PostScript code in the data fork which \OzTeX\ uses
when PostScript printing and a corresponding PICT image in the resource fork
which \OzTeX\ uses when previewing or non-PostScript printing.
To include an EPSF file, use a command of the form:

\verb|\special{epsf=filename}|

\end{itemize}
Keywords and file names are case-insensitive
and spaces before the file name are ignored.
For example, \verb|\special{EPSF=FOO}| is the same as \verb|\special{epsf= foo}|.

To find a given \verb|\special| file, \OzTeX\ uses the same search strategy as
that for a \TeX\ input file.  It looks in the current folder first, and then in
the \TeX\ input folder(s).
The file name can also be a path name relative to the current folder, or a full
path name.  For example,
\begin{verbatim}
   \special{pict=:my-pict-files:foo}
\end{verbatim}
will include a file called \verb|foo| from a sub-folder called \verb|my-pict-files|
in the current folder.
Spaces and other special characters (like \verb|=|) can be included in a file
name or path name by enclosing them in double quotes.  For example,
\begin{verbatim}
   \special{pict="my pict file"}
\end{verbatim}
will include a file called \verb|my pict file|.
Using spaces and other unusual characters in a file name is not recommended,
particularly if \TeX's \verb|\input| command might be used to read the file
(as in the \verb|boxedeps.tex| and \verb|epsf.tex| macros).
Also avoid using double quotes in a file name.

The PICT/PNTG/EPSF \verb|\special| commands all allow you to preview graphics
in your DVI file, but if you have a choice, use EPSF files because:
\begin{enumerate}

\item
The output on a PostScript printer should be of much higher quality than a
similar PICT/PNTG image.

\item
A coloured EPSF picture will print correctly on a PostScript printer
(assuming it supports colour) even though \OzTeX\ will convert its PICT
resource into a black and white bitmap when previewing.

\item
The \verb|boxedeps.tex| and \verb|epsf.tex| macros can extract the
bounding box information in an EPSF file and position the image automatically.

\item
Encapsulated PostScript is supported on many other computers.

\end{enumerate}
When creating a PICT/PNTG file it doesn't really matter where you position
the picture; \OzTeX\ will convert it to a black and white bitmap,
find the smallest bounding box of all black pixels in the bitmap,
then place the bounding box so that its bottom left corner coincides
with the location of the \verb|\special|.

\OzTeX\ does much the same thing for an EPSF picture; it places the lower left
corner of the bounding box at the location of the \verb|\special|.
The only difference is that if the PICT~256 resource is being used
(during preview or non-PostScript printing) then \OzTeX\ makes no attempt to
determine the smallest bounding box of all black pixels in the picture.
This is because the picture's dimensions should match those of the
BoundingBox comment in the data fork
(\OzTeX\ will warn you if the dimensions differ by more than 3\,bp).

\OzTeX\ allows optional \verb|keyword=value| pairs after the file name
in a PICT/PNTG/EPSF \verb|\special|.
The keyword can also be terminated by a space.
Here are the currently supported keywords:
\begin{itemize}

\item
\verb|scale=|$n$ --
scales a picture by a factor $n$ ($n$ must be $> 0.0$ and $\le 100.0$).

\item
\verb|hscale=|$n$ --
sets the horizontal scale factor (and alters the aspect ratio).

\item
\verb|vscale=|$n$ --
sets the vertical scale factor (and alters the aspect ratio).

\item
\verb|width=|$bp$ --
sets the horizontal scale to get a picture at the desired width
($bp$ is a number $> 0.0$ and $\le 32000.0$ in bp units, where 72\,bp = 1\,in).
If no previous \verb|height| keyword has been used then the vertical scale is
set to the new horizontal scale to preserve the aspect ratio.

\item
\verb|height=|$bp$ --
sets the vertical scale to get a picture at the desired height.
If no previous \verb|width| keyword has been used then the horizontal scale is
set to the new vertical scale to preserve the aspect ratio.

\end{itemize}
If a particular keyword is used more than once in a single \verb|\special|
command then the last value is used.
An illegal keyword or value will produce an error message when previewing
or printing.  Synonyms exist for most keywords:
\begin{tabbing}
\indent \= \verb|vscale|\quad \=\kill
\> \verb|epsf|   \> =\quad \verb|eps| or \verb|epsfile|\\
\> \verb|pict|   \> =\quad \verb|pictfile|\\
\> \verb|pntg|   \> =\quad \verb|macpaint|\\
\> \verb|hscale| \> =\quad \verb|xscale|\\
\> \verb|vscale| \> =\quad \verb|yscale|\\
\> \verb|width|  \> =\quad \verb|wd|\\
\> \verb|height| \> =\quad \verb|ht|
\end{tabbing}
Here are some examples of how to use \verb|\special| commands:
\begin{enumerate}

\item
To include a picture at ``normal'' size:

\leavevmode\rlap{\hskip 4in
      \special{pntg=ozicon}}%
\verb|\special{pntg=ozicon}|

\item
To halve the size:

\leavevmode\rlap{\hskip 4in
      \special{pntg=ozicon scale=0.5}}%
\verb|\special{pntg=ozicon scale=0.5}|

\item
To double the width:

\leavevmode\rlap{\hskip 4in
      \special{pntg=ozicon hscale=2}}%
\verb|\special{pntg=ozicon hscale=2}|.

\item
To set the height to 0.2\,in and the width to 2\,in:

\leavevmode\rlap{\hskip 4in
      \special{pntg=ozicon ht=14.4 wd=144}}%
\verb|\special{pntg=ozicon ht=14.4 wd=144}|.

\item
To set the height to 0.5\,in and preserve the aspect ratio:

\leavevmode\rlap{\hskip 4in
      \special{pntg=ozicon ht=36}}%
\verb|\special{pntg=ozicon ht=36}|.

\end{enumerate}
The figure on page~\pageref{folders} of this User Guide was created by using
\begin{verbatim}
   \special{pntg=folders scale=0.72}
\end{verbatim}
to include an extract from a Macintosh screen dump.
The scale value of $0.72$ was chosen because it is a multiple of
$0.24 = 72/300$, where 72\,dpi is the resolution of the MacPaint bitmap
and 300\,dpi is the resolution of my printer.
This technique can improve the print quality of scaled bitmaps.

\newpage


\subsection{Compatibility with other DVI drivers}

To provide better \verb|\special| compatibility with \dvips\ and other
DVI drivers, \OzTeX\ can process \verb|\special| commands like
\begin{verbatim}
   \special{psfile=foo llx=100 lly=100 urx=172 ury=172 rwi=720 rhi=720}
\end{verbatim}
where \verb|rhi| is optional (it is used to change the aspect ratio).
Note that \verb|llx| and the other keywords shown above can only be used
after \verb|psfile|.  Their order doesn't matter.
It is best \emph{not} to type in such \verb|\special| commands yourself;
you should let \verb|epsf.tex| or \verb|boxedeps.tex| generate them.

The given file (\verb|foo| in the above example) should normally be an
EPSF file containing a BoundingBox comment.
For compatibility with Wilfried Ricken's Direct\TeX,
\OzTeX\ also allows PICT files in a PSFILE \verb|\special|.
If \verb|foo| is a file of type PICT then \OzTeX\ will read in the picture
stored in the data fork.
If the given file name ends in ``\verb|.pict|'' then \OzTeX\ will get the
picture from a PICT~256 resource (and if you put a suitable BoundingBox
comment in the data fork then \verb|epsf.tex| or \verb|boxedeps.tex|
can be used to position the image).

Note that if the given file does not contain a BoundingBox comment
(PICT files cannot have such a comment)
then you will need to supply the bounding box coordinates to \verb|epsf.tex|;
for example, \verb|\epsfbox[0 0 72 72]{foo}|.
The numbers must be given in bp units and in the following order:
lower left x, lower left y, upper right x, upper right y.


\subsection{Including PostScript files}

\OzTeX\ allows you to include a ``raw'' PostScript file
using \TeX's \verb|\special| command.  However, if you have a choice then
any of the methods described in the above sections          % XREF
are preferable because \OzTeX\ cannot preview such a file,
nor can it print the file on a non-PostScript printer.

Assuming you have a file called \verb|fig.ps| that contains
PostScript code for generating some sort of figure, the following command
can be used to include this figure in a \TeX\ or \LaTeX\ document:
\begin{verbatim}
   \special{fig.ps}
\end{verbatim}
When printing the DVI file, \OzTeX\ interprets the \verb|\special| argument as
a file name and then includes this file with the rest of the PostScript output.
If it can't find the file in the current folder then it looks in the PS folder(s).
Don't worry about removing any \verb|showpage| command at the end of
your PostScript file because \OzTeX\ temporarily disables it.

It may take a little practice to position the figure correctly.
The default PostScript origin is at the bottom left corner of the paper.
However, when you include a file, \OzTeX\ automatically moves the
origin to the position of the \verb|\special|.
You can move the figure about by shifting the \verb|\special| position,
or by using a \verb|translate| command in the PostScript file.
The latter option is faster because you don't have to run \TeX\ again.
Alternatively, you may prefer to place your figure at an absolute position on
the paper.  Simply use a command like \verb|initgraphics| in the PostScript
file.  The position of the \verb|\special| command then becomes irrelevant;
just make sure it's on the right page!

\OzTeX\ also allows arbitrary PostScript code to appear after the file name.
At least one space must be used to terminate the file name;
further characters are included as a new line at the {\em start\/} of
the given file.
For example,
\begin{verbatim}
   \special{fig.ps 2 1 scale}
\end{verbatim}
could be used to double the width of the figure.
This feature allows you to include the same PostScript file more than once,
but with a different starting line each time --- useful if you need to produce
the same diagram many times but with slight variations.


\subsection{Rotating \TeX\ material}
\label{rotation}

\OzTeX\ generates highly efficient PostScript code but it does so at the
expense of some \verb|\special| functionality.
Most DVI-to-PostScript translators allow you to do things like
use one \verb|\special| to start rotating \TeX\ text and another
to stop the rotation.
The way \OzTeX\ interprets a DVI page makes this impossible.
All the rules, fonts and \verb|\special|s are collected in separate lists
for later processing, so any sequential connection between these
various page elements is lost.

However, assuming you have a PostScript printer, there is a way you can
rotate arbitrary \TeX\ material using \OzTeX:
\begin{enumerate}

\item
Create a \TeX\ file that produces a \emph{single} page containing only the
material to be rotated (it's a good idea to turn off page numbers by using
\verb|\nopagenumbers| in Plain \TeX\ or \verb|\thispagestyle{empty}| in \LaTeX).

\item
\TeX\ this file, select ``Print DVI'' and save the PostScript output in a file
called, say, \verb|rotate.ps|.

\item
Edit \verb|rotate.ps| and make these changes:
\begin{enumerate}

\item
If \OzTeX\ used low-level PostScript to create \verb|rotate.ps| then
delete all lines from the top down to and including ``\verb|1 @bop0|''.
If standard PostScript printing was used to create \verb|rotate.ps| then
delete all lines from the top down to and including the line \emph{ending}
with ``\verb| @setup|'' (note the space before the \verb|@|).

\item
If low-level PostScript printing was used,
replace the single line ``\verb|1 @bop1|'' with these lines:
\begin{verbatim}
   0 0 transform         % get \special location in device coords
   mtrx setmatrix        % set TeX coords (units = dpi, res = 1in)
   itransform translate  % make \special location the new origin
   res 2 mul             % move right by 2in; adjust if necessary
   res -0.2 mul          % move up by 0.2in; adjust if necessary
   translate             % shift the origin
   -90 rotate            % 90 degrees anticlockwise
\end{verbatim}
If standard PostScript printing was used, replace all lines
from ``\verb|end % OzTeXdict|'' to ``\verb|1 @bop1|'' with the above lines.

\item
If you want the output to appear in a fixed position on the page
(regardless of the location of the \verb|\special| command)
then remove the lines containing
``\verb|0 0 transform|'' and ``\verb|itransform translate|''
(but keep the ``\verb|mtrx setmatrix|'' line).

\item
Delete all lines from the bottom of the file up to and including ``\verb|1 @eop|''.
\end{enumerate}

\item
Include \verb|\special{rotate.ps}| in the \TeX\ file in which you want the
rotated material to appear.  Leave an appropriate amount of
vertical space before the \verb|\special|.

\item
Run \TeX\ and print the DVI file.
Either low-level or standard PostScript printing will work at this stage.
If you need to shift the location of the rotated material then adjust the
\verb|translate| parameters in \verb|rotate.ps| (note that you don't need
to run \TeX\ again).

\end{enumerate}
The \texdocs\ folder contains two files,
\verb|rotate.tex| and \verb|table.tex|, which illustrate how this works.

The above method is not very practical if you have a lot of material that
needs to be rotated.  In such a situation you should consider using a macro
package that generates \verb|\special| commands targeted for \dvips;
see section~\ref{dv-sec}.


\section{Recovering from errors}

\OzTeX\ reports errors by displaying a message in the \OzTeX\ window
or in a dialog box near the top right corner of the screen.
In the latter case there are two types of error dialogs:
\begin{enumerate}
\item
Warning messages appear in a box with a single Continue button.
\item
Fatal messages appear in a box with a Quit button (which will quit \OzTeX).
\end{enumerate}
Most errors, particularly the serious ones, are accompanied by a beep.
Let's now look at the most likely errors you'll encounter and what you can
do to prevent them recurring.


\subsection{Errors when loading a configuration file}
\label{config-error}

If an error occurs while loading in a configuration file then \OzTeX\ will
display a suitable message in the \OzTeX\ window.
The error message will also include the line number in the file, although this
can be misleading if you do something like forget an ``\verb|=|'' character.
It is advisable to switch to your editor, fix the error and reload the
configuration file before attempting to do anything else, particularly if
the error is in the {\tt Default} file.
See section~\ref{config-syntax} for a precise
description of the syntax required in a configuration file.


\subsection{Errors when loading an encoding file}

These errors can occur when \OzTeX\ is loading a configuration file that
contains a list of PostScript fonts.
If \OzTeX\ complains that it can't find an encoding file then check the
PS folder(s) parameter in the configuration file.
The encoding files supplied with \OzTeX\ are all stored in
the \encfiles\ sub-folder in \psfiles.
\OzTeX\ does \emph{not} look in the current folder for an encoding file.

Various syntax errors are possible when reading an encoding file.
The resulting message should provide you with enough information to fix
the problem.
See the comments at the start of \stdenc\ for a detailed description of
the legal syntax.


\subsection{Errors when running \TeX}

Nearly all the errors you'll see when running \TeX\ will be the
result of mistakes in your input file.
\texbook\ is the best place to look for solutions, especially Chapters~6 and 27.
Lamport's \LaTeX\ manual also has a section devoted to errors.
The following errors are more likely to occur due to \OzTeX's particular
implementation of \TeX.

\subsubsection*{Can't find file}

There are a number of likely reasons why \TeX\ can't find a file:
\begin{enumerate}
\item
The file does not exist in either the current folder or in any of the
sub-folders within \texinputs.
If \TeX\ was looking for a format file then make sure it is in the
\texformats\ folder.
\item
You could have spelt the file name incorrectly.
\item
The file name might contain an illegal character.
A Macintosh file name can contain just about any character, but
\TeX\ is not so flexible.
Don't use spaces and avoid non-alphabetic characters in all file names
that might be seen by \TeX\null.
\end{enumerate}
If you see such an error then the best thing to do is hit
Command-C or Command-Dot to abort \TeX\ and either
rename the file or move it to the correct folder.

\subsubsection*{Not enough memory}

The most likely time you could run out of memory is when using \initex\ to
create a format file.
\initex\ typically requires more memory than \TeX\ --- just
how much more depends on the \TeX\ parameters in your configuration file.
If you do run out of memory then quit \OzTeX,
select the \OzTeX\ application icon, choose ``Get Info'' from the Finder's
File menu, and increase the preferred size.

\subsubsection*{Fatal format error}

You probably changed one of the critical \TeX\ parameters in your configuration
file and forgot to rebuild the format.
Run \initex\ and rebuild the offending format file (see page~\pageref{fmt-sec}).

\subsubsection*{\TeX\ capacity exceeded}
\label{capacity}

Such an error message will be accompanied by additional text
describing which parameter has been exceeded.
Before doing anything else, first check for some common errors.
If the exceeded parameter is \verb|stack_size| then make sure
you haven't defined an infinitely recursive macro.
If the exceeded parameter is \verb|buffer_size| then it is quite likely
that the lines in your input file are too long; possible causes include
using an editor that automatically wraps lines without inserting end-of-line
characters, or incorrectly transferring a text file from another computer
(like a PC) that uses a different end-of-line character.

Look at the list of \TeX\ parameters in your configuration file and check
if the exceeded parameter appears there; if it is listed then you might be
able to solve the problem by simply increasing the parameter's value and
reloading the configuration file.
Note that if you change the value of \verb|mem_top|, \verb|hash_size|,
\verb|hash_prime| or \verb|hyf_size| then you will also need to rebuild all
format files (see page~\pageref{fmt-sec}).


\subsection{Errors when viewing a DVI file}

\subsubsection*{Missing fonts}

During interpretation of a DVI page you may get a warning message if \OzTeX\ can't
find a PK file, or if a PostScript font's matching screen font is not installed.
Such warnings will only appear once for each missing font
(but not at all if the ``\verb|Ignore missing fonts|'' check box was selected).
The ``Page Info'' item indicates all missing fonts.
Note that \mf\ can be used to build a missing PK file; see section~\ref{mf-sec}.

\subsubsection*{Virtual fonts}

If \OzTeX\ detects a virtual font (like \verb|ptmr|), it will display a warning
message reminding you to run ``Fix VFs in DVI''.

\subsubsection*{Page off paper}

If \OzTeX\ detects that any part of a DVI page %%% (including a \verb|\special|)
is off the paper then it will beep and show a full view.
\TeX\ will often catch these errors
(e.g., overfull \verb|\hbox| or \verb|\vbox|)
but there are quite a few situations where it can't.
\TeX\ really has no idea about what paper size you intend to print its pages on.

If you're sure the problem isn't in your input file then
use the ``Page Info'' item to see what \OzTeX\ thinks the paper dimensions are.
You could have forgotten to reset the landscape option or you might have made
a mistake when changing the paper dimensions in a configuration file.

\subsubsection*{{\tt\char'134special} errors}

When interpreting a DVI page \OzTeX\ will check any \verb|\special| commands
and warn you about the following problems:
\begin{itemize}
\itemsep=0pt
\item
An unknown keyword.
\item
A file that can't be opened.
\item
A file type that does not match the first keyword (PICT/PNTG/EPSF).
\item
A bad value after an optional keyword.
\end{itemize}
No warnings appear if the ``Ignore bad \verb|\specials|'' check box was selected.


\subsection{Errors when printing a DVI file}

\OzTeX\ detects basically the same set of errors whether it is viewing or
printing a DVI file.  In the latter case the error messages appear in
the \OzTeX\ window along with a beep.
If you've been sensible and previewed the DVI file before printing it then
you should have discovered nearly all the errors (and fixed them).

To avoid wasting paper you should always view a DVI file before printing it
and choose ``Page Info'' to check for any missing fonts
(but don't worry about missing screen fonts if you have a PostScript printer).
Another way to check for errors is to send PostScript output to a file
instead of the printer, although this won't detect certain errors that
can only occur with a non-PostScript printer.

\subsubsection*{Printer errors}

While sending output to any type of printer you might get status messages
indicating a problem such as an empty paper tray or a paper jam.
Once you've fixed the problem printing can normally continue.

\subsubsection*{Can't open {\tt\char'134special} file}

\OzTeX\ expects the argument of a \verb|\special| command to contain
a file name.  It won't be able to open the file if you spelt its name
incorrectly or if the file isn't in the correct folder.

\subsubsection*{Bad {\tt\char'134special} command}

If \OzTeX\ detects any sort of error in a \verb|\special| command
then a suitable message will be displayed in the \OzTeX\ window.
Note that you will get an error message if you try to print a DVI file that
includes a ``raw'' PostScript file on a non-PostScript printer.
See section~\ref{graphics} for the \verb|\special| syntax and semantics
supported by \OzTeX.

\subsubsection*{PostScript errors}

You shouldn't see any errors in the PostScript code generated by \OzTeX,
but there may well be problems in a PostScript file included by \verb|\special|.
(You can always tell which is the culprit by commenting out the \verb|\special|
command.)
If you are sending the output to a printer rather than spooling software then
any PostScript error should cause a message to appear in the \OzTeX\ window.
Any further output will be flushed and printing cancelled.

So what can you do?  For starters, get the
{\sl PostScript Language Reference Manual\/} by Adobe Systems.
Debugging a PostScript program can be a frustrating experience.
Try downloading the error handler stored in \verb|errhandler.ps|.
If the problem isn't obvious then use \verb|print| and \verb|flush| commands
to isolate just where the error is occurring.
The Ghostscript program mentioned in ``Related Software'' can also be useful.

\subsubsection*{Non-PostScript scaling errors}
\label{scaling-probs}

Before \OzTeX\ starts non-PostScript printing, it checks to see that the
printer resolution parameter matches the actual resolution of your printer.
If the resolutions don't match then \OzTeX\ will warn you that scaling problems
may occur.  This warning appears just before the print dialog in case you want
to Cancel printing (you might have forgotten to switch to the correct
configuration file).

If you decide to go ahead and print the DVI file, you might see problems
such as horizontal gaps at regular intervals down each page.
\OzTeX\ prints a page by sending a sequence of horizontal bands to the printer.
The number of bands depends on how much memory is available (the band height
is displayed when showing statistics).  Scaling problems can result in gaps or
overlapping at band boundaries, but they can be avoided by bumping up \OzTeX's
memory to a suitably large value so that only one large band is needed to print
each page.


\section{Changing resource data}

This section is for people who know how to use a resource editor like ResEdit.
Most user preferences are stored as resources in a file called \ozprefs.
You might like to change the following resources in this file:
\begin{itemize}
\item
STR~200 and 201 specify the location and name of
the default configuration file.
\item
STR~300 to 309 specify the keyboard short cuts used when previewing
(see page~\pageref{shortcuts}).  All the resources are named, so it is easy
to see which string corresponds to which short cut.
\OzTeX\ uses the first character in each string.
You might need to open a string resource with the hex editor if you want
to insert a non-displayable character like Delete or Return.
\end{itemize}
Some read-only information is stored as resources in the \OzTeX\ application.
For example, STR~12345 specifies the name of the preferences file.
The MENU resources can also be modified.  You might want to change the
name of a menu item or add a new Command key equivalent.


\section{\OzTeX\ and Metafont}
\label{mf-sec}

All the dialog boxes used to print or view a DVI file have a check box
called ``Make missing PK fonts'' (only available in System~7 or later).
The state of the check box is remembered when \OzTeX\ quits.
If ``Make missing PK fonts'' is checked and \OzTeX\ detects a missing PK font
when printing or previewing a DVI file, then \mf\ will be called to
build the required PK file.

\OzTeX\ does not call \mf\ directly.  Instead it starts up MakeTeXPK,
another of Tom's programs.  The very first time this happens, \OzTeX\ will
ask you to find and select the MakeTeXPK application.
The selected application is remembered for future use.

MakeTeXPK calls \mf\ to build a GF (Generic Font) file, then it
calls GFtoPK to convert the GF file into a PK file.  \OzTeX\ uses the new
PK file to continue previewing or printing.
Note that the PK file is created in the PK-files folder.  You can either
keep the PK file there or move it into an appropriate sub-folder.
A PK file called {\tt foo.999pk} should be stored in a sub-folder called {\tt 999}.
If no such sub-folder exists then create one.

It is possible that the font creation process will fail.  For example,
\mf\ might not find the required {\tt .mf} input file.  Or you might decide
to cancel the process.  In such cases \OzTeX\ will report a missing PK font
and append a line of information to a file called \missfont\ in the
\pkfiles\ folder.

If ``Make missing PK fonts'' is \emph{not} checked then \OzTeX\ won't attempt to
create a missing PK font, but it will append a line to \missfont.
The \missfont\ file can be used later by MakeTeXPK to build all the
listed PK fonts.  For many people this might be more convenient than
having \OzTeX\ build PK fonts on the fly --- it can take quite a while for
\mf\ to create a font.

Unless you have a Power Mac (and Tom's native PPC version of \mf),
I recommend leaving ``Make missing PK fonts'' unchecked, at least initially.
Preview all your DVI files and select ``Page Info'' from the View menu.
If there are any missing PK fonts, \OzTeX\ will create a \missfont\ file.
Edit this file and remove any duplicate lines.
Start up MakeTeXPK, open \missfont, select Run and go to bed!  When you
wake up, all the PK files should have been created in the \pkfiles\ folder.

It is a good idea to delete (or rename) \missfont\ after using it to
build PK files.  \OzTeX\ simply appends missing font info to \missfont\ without
checking to see if that info already exists, and MakeTeXPK simply
builds all the listed PK files, even if they already exist.
(Tom and I might do something smarter one day, although it is quite easy
to remove duplicate lines from \missfont\ with a good text editor.)

If you preview a DVI file and select the ``Ignore missing fonts'' check box
then the ``Make missing PK fonts'' setting is ignored.  If a missing PK font
is detected then \OzTeX\ won't attempt to call MakeTeXPK, nor will it append
any information to \missfont.  This feature is useful when previewing
certain DVI files (like {\tt trip.dvi}) where you know there are missing fonts
but you have no desire to create them.


\subsection{Setting the Metafont mode}
\label{mfmode}

To be able to build a PK file, \mf\ needs to know what mode to use.
\OzTeX\ gets this information from a configuration file:
the printer and viewing resolutions each have an extra string parameter that
is simply passed on to \mf.

WARNING: The given strings must exactly match known \verb|mode_def| values
defined in the file {\tt modes.mf} which is kept in the {\tt mfinputs}
sub-folder of the \mff\ folder.
It is also important to make sure that a given resolution value matches the
\verb|pixels_per_inch| value in the corresponding \verb|mode_def|,
otherwise \mf\ won't create a suitable PK file.

The {\tt Default} config file sets both modes to {\tt laserwriter}.
You might need to change these modes, either by selecting one of the
supplied config files (StyleWriter, ImageWriter or Linotronic),   % XREF
or by editing the {\tt Default} config file.
If a mode string is empty (\verb|""|) then \mf\ will use the {\tt localfont}
mode which is currently equivalent to the {\tt laserwriter} mode.

Common modes for \OzTeX\ users are
{\tt laserwriter}, {\tt stylewriter}, {\tt imagewriter} and {\tt linohi}.
If none of these modes suit your particular printer then look in
{\tt modes.mf} to see if there is a suitable definition.  The most important
thing to look for is a \verb|pixels_per_inch| value that matches the resolution
of your printer.  If you can't find a matching \verb|mode_def| (unlikely), you
will have to create your own and run {\tt inimf} to build a new {\tt mf.base} file.
See {\tt Readme.mf} in the \mff\ folder for details.

NOTE:
I've set the {\tt stylewriter} \verb|mode_def| parameters in {\tt modes.mf}
to be the the same as the {\tt laserwriter} parameters
(except for \verb|pixels_per_inch| of course).
This was done so that both modes can share the same set of PK files.
People who are fussy about their pixels (or with better eyesight than me)
might want to optimize the {\tt stylewriter} parameters for that printer.


\section{\OzTeX\ and Dvips}
\label{dv-sec}

Tom Rokicki's \dvips\ is the most widely used DVI-to-PostScript driver.
It provides a number of sophisticated features that are not available in
\OzTeX's DVI-to-PostScript code.
The \OzTeX\ distribution includes Tom Kiffe's implementation of \dvips,
and \OzTeX\ can call it if you are using System~7 or later.

To call \dvips, just tick the ``Use DVIPS'' flag in the File menu and
then select either of the top two items in the same menu.
These items will have changed from ``Print DVI\,\ldots'' and ``Print foo.dvi''
to ``DVIPS\,\ldots'' and ``DVIPS foo.dvi''.
After opening the DVI file, \OzTeX\ displays a dialog like this:

\vbox to 2.4in{\label{dvipsdlg}\vfil
\noindent\hskip 1.0in\special{pntg=dvipsdlg scale=0.72}}

\bigskip

\noindent
This dialog is very similar to the one used for low-level PostScript printing
(see page~\pageref{lowpsprint}).  Here are the changes:
\begin{itemize}

\item
The ``Conserve VM'' check box is replaced by ``Compress PK fonts''.

\item
There is no ``Save PostScript file'' button.  In its place is an edit
box for entering extra \dvips\ options (\dvips\ has a \emph{lot} of options;
see {\tt dvips.txt} in the \dvf\ folder).   % XREF

\item
There is no ``Page increment'' edit box.
Add ``\verb|-A|'' to the extra options box to select odd \TeX\ pages,
or ``\verb|-B|'' to select even \TeX\ pages.

\end{itemize}
When you click on the DVIPS button, \OzTeX\ will display the selected
options and call \dvips.  The very first time this is done, \OzTeX\ will ask
you to find and select the \dvips\ application.
The selected application is remembered for future use.

Soon after starting up, \dvips\ loads the \configps\ file (stored in the {\tt ps}
sub-folder of the \dvf\ folder).  This sets up various default parameters
including the resolution and \mf\ mode for making missing PK fonts.
The \configps\ file currently contains suitable parameters for an Apple
LaserWriter at 300\,dpi.  You might want to edit \configps\ if you have
a different printer.  See the \dvips\ manual for more details; the source
for this Plain \TeX\ document is the {\tt dvips.tex} file in the \dvf\ folder.

If you have access to more than one type of PostScript printer then set
up \configps\ for the most commonly used printer.  To select parameters for
a different printer, enter ``\verb|-P xxx|'' in the extra \dvips\ options box.
This tells \dvips\ to load {\tt config.xxx} \emph{after} \configps.
Of course, you will need to create a file called {\tt config.xxx}.
The {\tt config.linohi} file defines suitable parameters for a Linotronic typesetter,
so to select output for this printer you would enter ``\verb|-P linohi|''.

Note that \dvips\ will only call \mf\ to build a missing PK font if
the ``Make missing PK fonts'' box was checked.  If not checked,
then \dvips\ (like \OzTeX) will append a line of information to
\missfont\ in the \pkfiles\ folder.

Given {\tt foo.dvi} as input, \dvips\ will create an output file called {\tt foo.ps}.
(Add ``\verb|-o filename|'' to the extra options box to create a different file.)
When \dvips\ finishes processing you can use the Transfer menu to start up
Tom's PrintPS program and print {\tt foo.ps}.
PrintPS does much the same job as \OzTeX's ``Send PostScript\,\ldots'' item.
PrintPS also has a handy item that automatically deletes the file after sending
it to the printer.


\subsection{Why use Dvips?}

There are some good reasons why you might want to use \dvips\ rather than
\OzTeX's DVI-to-PostScript translator:
\begin{itemize}

\item
The \dvips\ program runs on many different computer systems.

\item
The PostScript code generated by \dvips\ is more portable and conforms to
Adobe's document structuring conventions.
This allows other programs like {\tt psnup} and {\tt psselect}
(available in Tom's full CMac\TeX\ distribution)
to manipulate the \dvips\ output in many interesting ways.

\item
\dvips\ provides better support for sophisticated graphic operations like
rotation and colour changing.  In particular, \dvips\ fully supports the
\LaTeX\ {\tt graphics} package, including commands like \verb|\rotatebox| and
\verb|\colorbox| which \OzTeX's DVI translator does \emph{not} support.

\end{itemize}
Note that \dvips\ does not support the \OzTeX-specific \verb|\special| commands
for including PICT and PNTG files.  Likewise, \OzTeX\ does not support
many of the \dvips-specific \verb|\special| commands.  Before previewing a DVI
file with lots of \verb|\special| commands targeted at \dvips, it is a good idea
to turn on the ``Ignore bad \verb|\specials|'' check box.

One way to ensure \verb|\special| compatibility between \OzTeX\ and \dvips\ is to
restrict yourself to the inclusion of EPSF files using the macros in
{\tt boxedeps.tex} or {\tt epsf.tex}.
For an example of the latter, see {\tt epsftest.tex} in the \texdocs\ folder.
After \TeX ing this file (using the Plain format), not only will \OzTeX\ be
able to preview the DVI file, but both \OzTeX\ and \dvips\ will produce
identical output on a PostScript printer.
(\OzTeX\ can also produce the same output on a non-PostScript printer.)

WARNING: Do \emph{not} create DVI file names containing
``\verb|*|'', ``\verb|~|'' or ``\verb|/|''.
\OzTeX\ doesn't care, but \dvips\ has a Unix heritage and these characters
have special meanings which will prevent \dvips\ reading the file.
For these and other reasons, it is good policy to restrict yourself to
letters and digits when naming \TeX\ (and thus DVI) files.  If you really
need some sort of separating character then ``\verb|-|'' is a safe choice.


\section{More information}

Many \TeX-related books are available through TUG, the \TeX\ Users Group.
They also produce an excellent magazine called TUGboat.
Anybody planning to use \TeX\ a lot is strongly advised to join.
The ``\TeX\ Users Group'' item in the Help menu explains how to get in touch.

% mention local user groups and refer to list (from TTN) in above help file???

If you have access to the Internet then another good source of help and
information about \TeX-related topics is the {\tt comp.text.tex} newsgroup.

\end{document}
